API resource

More analytics

Period-over-period change, inbox performance (volume, response time, busiest hours), per-account post history, and account settings.

Analytics changed since a cursor

GET/v1/analytics/delta

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Cursor feed of the analytics snapshots that CHANGED, across every account you can read, in one paginated stream. Built for integrations that would otherwise call `GET /v1/analytics` once per connected account. Each page carries changes from many accounts at once, so your call count scales with how much actually changed rather than with how many accounts you have. Measured against a fleet of roughly 1,600 connected accounts: about 1,599 per-account analytics calls an hour became about 205 delta calls an hour, a 7.8x reduction.

Query parameters

cursorstring

Opaque cursor from a previous response's `nextCursor`. Omit it to start from now: the response is then an empty page carrying the feed's current position. Rejected with a `400` when malformed, or when older than the retention window.

limitstring

Page size. Out-of-range values are a 400, never a silent clamp.

platformstring

Filter to a single platform (for example "youtube"). Omit for every platform.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/delta" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "data": [],
  "nextCursor": "v1.WyIyMDI2LTA5LTAxIDE3OjEyOjA0IiwiNjVmMWMwYTllMmI1YWYwMDEyYWIzNGNkIl0",
  "hasMore": true
}

Get inbox messaging volume

GET/v1/analytics/inbox/volume

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Daily inbox messaging volume + breakdowns. Folds the raw messaging events into three projections so the client can render the volume chart, KPI strip, and per-platform stacked bar from a single call. Max date range is 365 days.

Query parameters

fromDatestringrequired

Inclusive lower bound (YYYY-MM-DD). Required.

toDatestring

Inclusive upper bound (YYYY-MM-DD). Defaults to today.

platformstring

Filter by single platform (facebook, instagram, twitter, etc.).

accountIdstring

No description

sourcestring

Filter by metadata.source lineage (human, workflow, sequence, broadcast, comment_automation, api, contact, platform).

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/volume?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "from": "string",
  "to": "string",
  "summary": {
    "received": 0,
    "sent": 0,
    "read": 0,
    "failed": 0,
    "uniqueConversations": 0
  },
  "timeseries": [
    {
      "date": "2026-09-25T00:00:00.000Z",
      "sent": 0,
      "received": 0,
      "read": 0,
      "failed": 0
    }
  ],
  "byPlatform": [
    {
      "platform": "instagram",
      "sent": 0,
      "received": 0,
      "read": 0,
      "failed": 0
    }
  ]
}

Get inbox response-time stats

GET/v1/analytics/inbox/response-time

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Time-to-first-response stats. Pairs each received message with the next sent message in the same conversation and reports the delta as both summary statistics and a fixed-bucket histogram suited for the analytics page's TTR chart. `sampleSize` reflects only conversations that received AND got a reply in the window. Received-but-never-answered conversations are excluded. Compare against /v1/analytics/inbox/volume's `summary.received` to compute reply rate. Max date range is 365 days.

Query parameters

fromDatestringrequired

No description

toDatestring

No description

platformstring

No description

accountIdstring

No description

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/response-time?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "from": "string",
  "to": "string",
  "summary": {
    "sampleSize": 0,
    "medianSeconds": 0,
    "p90Seconds": 0,
    "p99Seconds": 0,
    "meanSeconds": 0,
    "fastestSeconds": 0,
    "slowestSeconds": 0
  },
  "histogram": [
    {
      "bucket": "string",
      "lowerSeconds": 0,
      "upperSeconds": 0,
      "count": 0
    }
  ]
}

Get day × hour heatmap

GET/v1/analytics/inbox/heatmap

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Day-of-week × hour-of-day breakdown of inbox messages. Buckets are sparse: only cells with at least one event are returned; clients zero-fill the rest to render the full 7×24 grid. The `dow` field follows ClickHouse's `toDayOfWeek` convention (1 = Monday … 7 = Sunday). Max date range is 365 days.

Query parameters

fromDatestringrequired

No description

toDatestring

No description

platformstring

No description

accountIdstring

No description

sourcestring

No description

actionstring

Narrow to a single event type. "all" or omitted means no filter.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/heatmap?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "from": "string",
  "to": "string",
  "buckets": [
    {
      "dow": 0,
      "hour": 0,
      "received": 0,
      "sent": 0,
      "read": 0
    }
  ]
}

Get inbox source breakdown

GET/v1/analytics/inbox/source-breakdown

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Breakdown of inbox messages by their lineage source (the `metadata.source` field set at ingest time: human / workflow / sequence / broadcast / comment_automation / api / contact / platform). Each source row also carries a per-platform sub-split. Max date range is 365 days.

Query parameters

fromDatestringrequired

No description

toDatestring

No description

platformstring

No description

accountIdstring

No description

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/source-breakdown?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "from": "string",
  "to": "string",
  "sources": [
    {
      "source": "string",
      "received": 0,
      "sent": 0,
      "read": 0,
      "byPlatform": [
        {
          "platform": "instagram",
          "received": 0,
          "sent": 0,
          "read": 0
        }
      ]
    }
  ]
}

Get top accounts by inbox volume

GET/v1/analytics/inbox/top-accounts

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Leaderboard of accounts by inbox message volume. Decorates each row with display labels from the live SocialAccount record (so the UI shows username + displayName, not only an ID). Accounts that no longer map to a SocialAccount surface as "(disconnected)" so the row stays visible. Max date range is 365 days.

Query parameters

fromDatestringrequired

No description

toDatestring

No description

platformstring

No description

sourcestring

No description

limitstring

Cap on returned rows. Lower than the posting listing's 100 because each row triggers a SocialAccount Mongo lookup.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/top-accounts?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "from": "string",
  "to": "string",
  "accounts": [
    {
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "instagram",
      "displayName": "string",
      "username": "string",
      "received": 0,
      "sent": 0,
      "total": 0,
      "conversations": 0,
      "medianResponseSeconds": 0,
      "repliedCount": 0
    }
  ]
}

List conversation analytics

GET/v1/analytics/inbox/conversations

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Per-conversation listing with per-row totals + first/last message timestamps. The inbox analog of GET /v1/analytics (posts listing): same filter shape, same pagination, same sort/order semantics. Use as the entry point for the per-conversation analytics drawer at /v1/analytics/inbox/conversations/{conversationId}. Rows are enriched with the conversation's participant info (`participantName`, `participantUsername`, `participantPicture`) and last-message preview by joining the Conversation document scoped to the caller's team. Max date range is 365 days.

Query parameters

fromDatestringrequired

No description

toDatestring

No description

platformstring

No description

accountIdstring

No description

sourcestring

No description

limitstring

No description

pagestring

No description

sortBystring

No description

orderstring

No description

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/conversations?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "from": "string",
  "to": "string",
  "items": [
    {
      "conversationId": "string",
      "mongoId": "string",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "instagram",
      "participantName": "string",
      "participantUsername": "string",
      "participantPicture": "string",
      "lastMessage": "string",
      "totalMessages": 0,
      "received": 0,
      "sent": 0,
      "read": 0,
      "failed": 0,
      "firstMessageAt": "2026-09-25T00:00:00.000Z",
      "lastMessageAt": "2026-09-25T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 0,
    "total": 0,
    "totalPages": 0,
    "hasMore": true
  }
}

Get conversation analytics

GET/v1/analytics/inbox/conversations/{conversationId}

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Per-conversation inbox analytics. The inbox analog of /v1/analytics/post-timeline: one conversation, daily totals, source mix. The {conversationId} path param accepts EITHER the Mongo `_id` of the Conversation document OR its `platformConversationId` (the same identity used by metadata.conversationId at ingest time). Ownership is verified in MongoDB against the caller's team before the Tinybird query fires. Max date range is 365 days.

Path parameters

conversationIdstringrequired

Mongo _id or platformConversationId.

Query parameters

fromDatestringrequired

No description

toDatestring

No description

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/inbox/conversations/conv_9WFW-MsJBK43x7I-Ij21W7ZmevMKhsEYFQ2Bv8Kx5Rt?fromDate=%3CfromDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "conversationId": "string",
  "mongoId": "string",
  "platform": "instagram",
  "from": "string",
  "to": "string",
  "summary": {
    "received": 0,
    "sent": 0,
    "read": 0,
    "failed": 0,
    "totalMessages": 0,
    "firstMessageAt": "2026-09-25T00:00:00.000Z",
    "lastMessageAt": "2026-09-25T00:00:00.000Z"
  },
  "timeseries": [
    {
      "date": "2026-09-25T00:00:00.000Z",
      "sent": 0,
      "received": 0,
      "read": 0,
      "failed": 0
    }
  ],
  "bySource": [
    {
      "source": "string",
      "count": 0
    }
  ]
}

List posts published on the platform

GET/v1/accounts/{accountId}/posts

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Returns the 25 most recent posts that exist on the platform for a connected account, read live from the platform API. This covers everything on the account, including posts that were never created through Creator OS. Use it to obtain the platform's own post id, which the analytics endpoints take as input. On YouTube the returned `id` is the video ID that `GET /v1/analytics/youtube/daily-views`, `/video-retention` and `/demographics` expect as `videoId`, so this endpoint is what backs a video picker in your own UI.

Path parameters

accountIdstringrequired

No description

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/posts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "status": "success",
  "posts": [
    {
      "id": "string",
      "platform": "instagram",
      "message": "string",
      "createdTime": "2026-09-25T00:00:00.000Z",
      "permalink": "string",
      "picture": "string",
      "mediaType": "string",
      "commentCount": 0,
      "likeCount": 0,
      "reactionCount": 0,
      "shareCount": 0,
      "cid": "string",
      "subreddit": "string"
    }
  ],
  "lastUpdated": "string"
}

Move account to another profile

PATCH/v1/accounts/{accountId}

Works on: Instagram, TikTok, YouTube, X, Threads, Facebook, LinkedIn

Moves a connected account to a different profile owned by the same user. The target profile must belong to the same user as the account. For API keys restricted to specific profiles, BOTH the source account's current profile AND the target profile must be in the key's allowed set. Calls with a target profile outside the key's scope return 403.

Path parameters

accountIdstringrequired

No description

curl -X PATCH "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "message": "string"
}

PreviousPosting queue NextCLI reference