API resource

Dashboard and verified tracking

One call for a whole analytics dashboard (totals, follower growth, a per-day series, top and recent posts, the previous period to compare), plus verified tracking: open a window on any post, even one you did not publish, and every reading comes from the network itself. Authenticity scores flag posts whose numbers look inflated. Facebook visitor and tagged posts are what other people posted on or about your Page.

Get an analytics dashboard

GET/v1/analytics/dashboard

Works on: Every network

Everything an analytics dashboard needs in one call: window totals, follower growth, a per-day series, top posts, recent posts and, optionally, the same figures for the previous period. All dates are UTC days. ### Daily and total metrics Daily and total metrics use received attribution: each day holds the engagement that arrived that day, on any post. So totals is always the sum of daily. ### Post lists topPosts and recentPosts list posts published in the window with their lifetime metrics. A post cross-posted to several platforms appears once per platform.

Query parameters

platformstring

Platform to cover (e.g. "instagram"), or "all".

fromDatestringrequired

First day of the window (YYYY-MM-DD, inclusive).

toDatestringrequired

Last day of the window (YYYY-MM-DD, inclusive). May equal fromDate. The window covers at most 366 days.

comparestring

Set to "previous_period" to also return previousTotals and previousFollowers for the window of the same length that ends the day before fromDate. One of: previous_period.

topPostsinteger

How many top posts to return, ranked by engagement (likes, comments, shares and saves, the same sum as daily engagement).

recentPostsinteger

How many of the most recently published posts to return.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/dashboard?fromDate=%3CfromDate%3E&toDate=%3CtoDate%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "dateRange": {
    "fromDate": "2026-10-10T00:00:00.000Z",
    "toDate": "2026-10-10T00:00:00.000Z"
  },
  "totals": {
    "impressions": 0,
    "reach": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "saves": 0,
    "clicks": 0,
    "views": 0,
    "engagementRate": 0
  },
  "previousTotals": {
    "impressions": 0,
    "reach": 0,
    "likes": 0,
    "comments": 0,
    "shares": 0,
    "saves": 0,
    "clicks": 0,
    "views": 0,
    "engagementRate": 0
  },
  "followers": {
    "current": 0,
    "gained": 0,
    "byAccount": [
      {
        "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "social",
        "current": 0,
        "gained": 0
      }
    ]
  },
  "previousFollowers": {
    "current": 0,
    "gained": 0,
    "byAccount": [
      {
        "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
        "platform": "social",
        "current": 0,
        "gained": 0
      }
    ]
  },
  "daily": [
    {
      "date": "2026-10-10T00:00:00.000Z",
      "impressions": 0,
      "reach": 0,
      "engagement": 0,
      "views": 0,
      "followersGained": 0
    }
  ],
  "topPosts": [
    {
      "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
      "platform": "social",
      "publishedAt": "2026-10-10T00:00:00.000Z",
      "metrics": {
        "impressions": 0,
        "reach": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "saves": 0,
        "clicks": 0,
        "views": 0,
        "engagementRate": 0
      }
    }
  ],
  "recentPosts": [
    {
      "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
      "platform": "social",
      "publishedAt": "2026-10-10T00:00:00.000Z",
      "metrics": {
        "impressions": 0,
        "reach": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "saves": 0,
        "clicks": 0,
        "views": 0,
        "engagementRate": 0
      }
    }
  ],
  "dataAsOf": "2026-10-10T00:00:00.000Z"
}

List tracking windows

GET/v1/analytics/tracking

Works on: Every network

Lists the tracking windows you can see, newest first. Each window carries the latest verified numbers we read from the platform.

Query parameters

accountIdstring

Only windows for this connected account.

statusstring

Only windows in this status. One of: open, completing, completed, cancelled.

limitinteger

Page size.

skipinteger

Number of windows to skip.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/tracking" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "windows": [
    {
      "id": "string",
      "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
      "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
      "platform": "tiktok",
      "platformPostId": "string",
      "startsAt": "2026-10-10T00:00:00.000Z",
      "endsAt": "2026-10-10T00:00:00.000Z",
      "status": "open",
      "finalReadAt": "2026-10-10T00:00:00.000Z",
      "completionReason": "final_read",
      "requestedBy": "string",
      "latest": {
        "views": 0,
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "saves": 0,
        "syncedAt": "2026-10-10T00:00:00.000Z"
      }
    }
  ]
}

Open a tracking window

POST/v1/analytics/tracking

Works on: Every network

Starts watching a post's views and engagement. Creator OS fetches the numbers from the platform itself on its regular analytics sync, so every reading is verified. It is a value we read from the platform, never one the creator or the caller reported. ### The window - Runs for trackingDays (30 by default, 90 at most). - Ends with one final read, after which the post.tracking_completed webhook fires. ### Identifying the post Send either postId (an external post id from Creator OS), or accountId together with the post's url. ### Responses - 201: a new window was opened.

Body

postIdstring

Id of an external post. Required unless accountId and url are both sent.

accountIdstring

Connected account the post belongs to. Send together with url.

urlstring

Public URL of the post on the platform. Send together with accountId.

trackingDaysinteger

How many days the window stays open.

requestedBystring

Free-form label for who asked for the window. It is stored and returned as given.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/analytics/tracking" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9"
  }'
Response 200
{
  "window": {
    "id": "string",
    "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "platform": "tiktok",
    "platformPostId": "string",
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "open",
    "finalReadAt": "2026-10-10T00:00:00.000Z",
    "completionReason": "final_read",
    "requestedBy": "string",
    "latest": {
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saves": 0,
      "syncedAt": "2026-10-10T00:00:00.000Z"
    }
  }
}

Get a tracking window

GET/v1/analytics/tracking/{windowId}

Works on: Every network

Returns one tracking window with the latest verified numbers we read from the platform. Once the window has completed, finalReadAt and completionReason say how it closed.

Path parameters

windowIdstringrequired

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/tracking/obj_Tw3Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "window": {
    "id": "string",
    "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "platform": "tiktok",
    "platformPostId": "string",
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "open",
    "finalReadAt": "2026-10-10T00:00:00.000Z",
    "completionReason": "final_read",
    "requestedBy": "string",
    "latest": {
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saves": 0,
      "syncedAt": "2026-10-10T00:00:00.000Z"
    }
  }
}

Cancel a tracking window

DELETE/v1/analytics/tracking/{windowId}

Works on: Every network

Stops tracking and returns the window with its final status. A window that already completed keeps its completed status and its final read. A cancelled window gets no final read and fires no post.tracking_completed webhook.

Path parameters

windowIdstringrequired

curl -X DELETE "https://creatoros-production-5658.up.railway.app/v1/analytics/tracking/obj_Tw3Kq8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "window": {
    "id": "string",
    "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
    "platform": "tiktok",
    "platformPostId": "string",
    "startsAt": "2026-10-10T00:00:00.000Z",
    "endsAt": "2026-10-10T00:00:00.000Z",
    "status": "open",
    "finalReadAt": "2026-10-10T00:00:00.000Z",
    "completionReason": "final_read",
    "requestedBy": "string",
    "latest": {
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saves": 0,
      "syncedAt": "2026-10-10T00:00:00.000Z"
    }
  }
}

Get post samples

GET/v1/analytics/samples

Works on: Every network

Returns the raw readings behind a post's numbers, oldest first. Each sample is one analytics sync: the views and engagement as the platform reported them at syncedAt. Creator OS only stores what it fetched from the platform, so nothing here was self-reported. ### Null values - shares and saves are null on platforms that do not return that counter, which is different from a real zero. - watchSeconds and completionRate are null when the platform gives no watch signal. The newer way to read this is GET /v1/metrics/posts with include=samples, for up to 10 posts in one request.

Query parameters

postIdstringrequired

The post to read samples for. Accepts an external post id, a platform post id or a Creator OS post id.

fromDatestring

Earliest sample to return (ISO 8601).

toDatestring

Latest sample to return (ISO 8601).

limitinteger

Maximum number of samples.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/samples?postId=post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
  "samples": [
    {
      "syncedAt": "2026-10-10T00:00:00.000Z",
      "views": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saves": 0,
      "watchSeconds": 0,
      "completionRate": 0
    }
  ]
}

List authenticity scores

GET/v1/analytics/authenticity

Works on: Every network

Lists the stored authenticity scores for one connected account, newest first. Requires the Analytics add-on. Scores are 0 to 100 and come from Creator OS's own model over verified platform samples. ### Filters - minScore and maxScore: find posts that look inflated. - from and to: bound when the score was computed. The newer way to read scores is GET /v1/metrics/posts with metrics=authenticityScore or include=authenticity. This route keeps the score filters (minScore, maxScore, from, to).

Query parameters

accountIdstringrequired

The connected account to list scores for.

minScoreinteger

Only scores at or above this value.

maxScoreinteger

Only scores at or below this value.

fromstring

Only scores computed at or after this time (ISO 8601).

tostring

Only scores computed at or before this time (ISO 8601).

limitinteger

Page size.

skipinteger

Number of scores to skip.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/authenticity?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "scores": [
    {
      "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
      "score": 0,
      "confidence": 0,
      "reasons": [
        {}
      ],
      "version": "string",
      "computedAt": "2026-10-10T00:00:00.000Z",
      "sampleCount": 0
    }
  ]
}

Get a post's authenticity score

GET/v1/posts/{postId}/authenticity

Works on: Every network

Returns Creator OS's authenticity score for a post: an integer from 0 to 100 where higher means the view pattern looks more like organic viewing. The score is ours. It is computed only from the verified samples we fetched from the platform, never from anything the creator or caller reported. - reasons lists each factor that lowered it with its weight in points. - confidence (0 to 1) says how much data the score rests on. A stored score newer than 30 minutes is returned as is, otherwise it is recomputed. The post.authenticity_changed webhook fires when a score crosses 40.

Path parameters

postIdstringrequired

An external post id, a platform post id or a Creator OS post id.

curl "https://creatoros-production-5658.up.railway.app/v1/posts/post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9/authenticity" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "postId": "post_V9cK2mQ7xL4pR8tN1wZ6bH3jF5dS0aG7eU2iO4kY9",
  "score": 0,
  "confidence": 0,
  "reasons": [
    {
      "code": "late_block",
      "weight": 0
    }
  ],
  "version": "string",
  "computedAt": "2026-10-10T00:00:00.000Z",
  "sampleCount": 0
}

Sync an external post

POST/v1/posts/sync-external

Works on: Every network

Fetch an account's latest external posts (published directly on the platform, not through Creator OS) on demand. A newly published post is then retrievable within seconds instead of waiting for the background sync, which refreshes each account at most every ~90 minutes. Primary use case: verifying a submitted post. When a user publishes on the platform and immediately pastes the post URL into your app, call this with accountId plus url (or postId) to confirm the post exists and return its metadata.

Body

accountIdstringrequired

account id whose posts to sync. Must be connected to Creator OS.

urlstring

The post URL to locate. Optional. Provide url or postId to return a specific post; omit both to refresh and return the account's recent posts.

postIdstring

The platform post/media/video id to locate, as an alternative to url. Optional.

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/posts/sync-external" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r"
  }'
Response 200
{
  "synced": {
    "postsFound": 0,
    "postsSynced": 0,
    "skipped": true
  },
  "found": true,
  "post": {
    "platform": "social",
    "platformPostId": "string",
    "platformPostUrl": "string",
    "content": "string",
    "publishedAt": "2026-10-10T00:00:00.000Z",
    "mediaType": "string",
    "thumbnailUrl": "string",
    "mediaItems": [
      {}
    ],
    "mediaProductType": "string",
    "isAiGenerated": true,
    "isSharedToFeed": true,
    "mediaAudioType": "string",
    "upcomingStartAt": "2026-10-10T00:00:00.000Z",
    "isOwner": true,
    "analytics": {
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "saves": 0,
      "sends": 0,
      "clicks": 0,
      "views": 0,
      "reach": 0,
      "impressions": 0,
      "engagementRate": 0,
      "lastUpdated": "2026-10-10T00:00:00.000Z"
    }
  },
  "posts": [
    {
      "platform": "social",
      "platformPostId": "string",
      "platformPostUrl": "string",
      "content": "string",
      "publishedAt": "2026-10-10T00:00:00.000Z",
      "mediaType": "string",
      "thumbnailUrl": "string",
      "mediaItems": [
        {}
      ],
      "mediaProductType": "string",
      "isAiGenerated": true,
      "isSharedToFeed": true,
      "mediaAudioType": "string",
      "upcomingStartAt": "2026-10-10T00:00:00.000Z",
      "isOwner": true,
      "analytics": {
        "likes": 0,
        "comments": 0,
        "shares": 0,
        "saves": 0,
        "sends": 0,
        "clicks": 0,
        "views": 0,
        "reach": 0,
        "impressions": 0,
        "engagementRate": 0,
        "lastUpdated": "2026-10-10T00:00:00.000Z"
      }
    }
  ]
}

List visitor posts on a Facebook Page

GET/v1/accounts/{accountId}/facebook-visitor-posts

Works on: Every network

Returns the posts other people published on the connected Facebook Page, newest first. A Page without visitor posts returns an empty data array. ### What is returned Creator OS reads the Page feed (Graph /{page-id}/feed, which works on New Pages Experience Pages, unlike the deprecated visitor_posts edge). It drops: - the posts the Page published itself - the posts other people published on their own timeline that only tag the Page ### Pagination Cursor-paginated: pass nextCursor from the previous response as cursor to read the next page.

Path parameters

accountIdstringrequired

The ID of a connected Facebook Page account.

Query parameters

limitinteger

Number of Page feed entries to scan. The Page's own posts are dropped from them.

cursorstring

The nextCursor of the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/facebook-visitor-posts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": [
    {
      "id": "string",
      "message": "string",
      "createdTime": "2026-10-10T00:00:00.000Z",
      "from": {
        "id": "string",
        "name": "string"
      },
      "permalinkUrl": "string",
      "media": {
        "mediaType": "image",
        "thumbnailUrl": "string",
        "mediaItems": []
      }
    }
  ],
  "nextCursor": "string"
}

List the posts a Facebook Page is tagged in

GET/v1/accounts/{accountId}/facebook-tagged-posts

Works on: Every network

Returns the public posts where other people or Pages tagged the connected Facebook Page, as Meta returns them from the Page's tagged edge. Cursor-paginated: pass nextCursor from the previous response as cursor to read the next page. nextCursor is null when there are no more pages. Meta does not say whether a page is the last one, so the final page can come back empty with nextCursor null. Works for facebook accounts with a Page selected.

Path parameters

accountIdstringrequired

The ID of a connected Facebook account.

Query parameters

limitinteger

Page size.

cursorstring

The nextCursor of the previous page.

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/facebook-tagged-posts" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"
Response 200
{
  "data": [
    {
      "id": "string",
      "message": "string",
      "createdTime": "2026-10-10T00:00:00.000Z",
      "taggedTime": "2026-10-10T00:00:00.000Z",
      "permalinkUrl": "string",
      "pictureUrl": "string",
      "from": {
        "id": "string",
        "name": "string"
      }
    }
  ],
  "nextCursor": "string"
}