Fuxux Analytics API

openapi: 3.2.0
info:
  title: Fuxux Analytics API
  version: 1.1.0
  description: 'Schedule and publish to 14 social platforms, manage connected accounts, upload media, and generate AI captions from your own apps, agents, or CI pipelines. Every endpoint below mirrors something you can do in the Fuxux dashboard. ## Access

    The API is included in every paid plan (Creator, Growth or Pro), at no extra cost. API keys aren''t available on the Free plan. ## Authentication

    Send your **personal API key** on every authenticated request:


    `Authorization: Bearer fx_live_…`


    Create keys on the **API keys** page of the dashboard. The full secret is shown **only once** when you create or rotate a key; store it in an environment variable. You can have up to **10 active keys** and create or rotate up to **20 a day**. Use one key per integration: rotating a key revokes the old one, so a shared key breaks every client that uses it. `GET /api/settings/profile` is the recommended connection test: it''s cheap and has no side effects. A key on an account without a paid plan is refused with 401, like a wrong key. ## Posting

    `POST /api/posts` publishes immediately, schedules with `scheduled_at`, or saves a draft with `draft: true`. Send `scheduled_at` with `Z` or an offset (`2027-01-15T09:30:00-08:00`): a time without one is read as UTC, not as the account''s time zone. `captions` maps each platform id to its caption. Add `targets` to choose exact accounts and per-platform options; it is how you pick between several accounts on one platform. Platform ids: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `youtube`, `bluesky`, `threads`, `pinterest`, `discord`, `kick`, `twitch`, `telegram`, `slack`. Reddit and Google Business Profile aren''t supported. Each platform''s own rules still apply (for example, Instagram and TikTok need media). Connect accounts in Fuxux first, then list them with `GET /api/accounts`. ## Rate limits and polling

    **120 requests/min per key** and **300/min per account** across all keys; creating posts is limited to **30 per 5 minutes**. Over a limit you get **429** with `Retry-After` (seconds) — wait that long. Don''t poll: publishing settles on the order of minutes, so check a post''s status at most once a minute (or use a webhook). ## Webhooks

    Set a webhook URL on the API keys page to receive a `post.finished` event when a post''s publishing completes. In a team space, the space owner''s webhook also receives the events for posts their members publish. Its `status` is `published` when at least one platform succeeded; `outcome` is exact (`published`, `partially_failed` or `failed`) and `failed_platforms` lists what failed. The body also carries the post''s `workspace_id` (space) and, in each result, the `account_id` of the connected account. A delivery that gets no answer, a 5xx, 408 or 429 is retried with growing waits (about 2 min, 10 min, 30 min, 2 h, 6 h; 6 attempts in all); any other 4xx is final. Every attempt has the same body and `X-Fuxux-Delivery-Id` (drop repeats by it) and an `X-Fuxux-Delivery-Attempt` number. Each delivery is signed: `X-Fuxux-Signature: sha256=` is the HMAC-SHA256 of the raw body with your webhook secret.'
servers:
- url: https://www.fuxux.com
  description: Production
tags:
- name: Analytics
  description: Publishing analytics
paths:
  /api/analytics:
    get:
      tags:
      - Analytics
      summary: Publishing analytics
      parameters:
      - name: days
        in: query
        schema:
          type: integer
          enum:
          - 7
          - 14
          - 30
          - 90
          default: 30
        description: Sliding window length for chart and breakdown; invalid values default to 30.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Analytics needs a Creator, Growth or Pro plan (in a team space, the space owner's plan), or the key's space is no longer available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited; honor `Retry-After`
      operationId: getApiAnalytics
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: Present on some refusals, for example `post_quota_reached`, `x_allowance`, `reddit_web_only`.
    EngagementTotals:
      type: object
      properties:
        likes:
          type: integer
        comments:
          type: integer
        shares:
          type: integer
        views:
          type: integer
        impressions:
          type: integer
        reach:
          type: integer
    AnalyticsResponse:
      type: object
      properties:
        chartDays:
          type: integer
          enum:
          - 7
          - 14
          - 30
          - 90
        summary:
          type: object
          properties:
            totalPublished:
              type: integer
            publishedThisMonth:
              type: integer
            publishedLastMonth:
              type: integer
            momChange:
              type: integer
              nullable: true
            scheduled:
              type: integer
            successRate:
              type: number
              nullable: true
              description: '% of variants published successfully in the selected window'
        dailyPosts:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                description: YYYY-MM-DD
              count:
                type: integer
        platformBreakdown:
          type: array
          items:
            type: object
            properties:
              platform:
                type: string
              name:
                type: string
              published:
                type: integer
              failed:
                type: integer
              engagement:
                $ref: '#/components/schemas/EngagementTotals'
              postsWithInsights:
                type: integer
                description: How many of this platform's published posts in the window have synced engagement data
        engagement:
          allOf:
          - $ref: '#/components/schemas/EngagementTotals'
          - type: object
            properties:
              postsWithInsights:
                type: integer
                description: How many published posts in the window have synced engagement data
          description: Aggregated real engagement (likes/comments/shares/views/impressions/reach) synced from the platforms for posts published in the selected window. engagement_rate is not summed here since it's a per-post percentage; it's only present per-post on recentPosts[].post_variants[].insights.
        recentPosts:
          type: array
          items:
            type: object
            additionalProperties: true
            description: Each item's post_variants[] may include an `insights` object (likes, comments, shares, views, impressions, reach, engagement_rate, and other platform-specific fields) and `insights_updated_at`, where synced.