API resource
Metrics
One read API over everything that is synced: posts (published through Creator OS or directly on the network), accounts, inbox activity and, with the Ads add-on, ads, campaigns and ad accounts, by id, day by day, as a list or grouped. GET /v1/metrics/catalog lists every entity, field, filter and grouping. The platform queries run a native Meta, Google Ads or TikTok Ads report on one ad account and return its rows unchanged.
List the metrics, groupings and limits of each metrics endpoint
/v1/metrics/catalogWorks on: Every network
Query parameters
entitystringOnly this entity. One of: posts, accounts, inbox, insights, ads, campaigns, ad-accounts.
platformstringOnly the metrics, sorts, includes and groupBy values this platform has. Every entity is still listed. One of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, whatsapp, discord, slack, google, microsoft, openai.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/catalog" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
{
"entity": "posts",
"path": "string",
"requiredScope": [
"string"
],
"maxScopeIds": {},
"maxRangeDays": 0,
"defaultRangeDays": "string",
"granularities": [
"total"
],
"sorts": [
"string"
],
"maxSortedRows": "string",
"includes": [
{}
],
"groupBy": [
{}
],
"attributions": [
{}
],
"origins": [
"string"
],
"metrics": [
{}
]
}
],
"pagination": {
"nextCursor": "string",
"hasMore": true
}
}Read post metrics by id, day by day, as a list, or grouped
/v1/metrics/postsWorks on: Every network
Query parameters
postIdstringComma-separated post ids (Creator OS or external), up to 100.
platformPostIdstringComma-separated ids the platform gave the posts (a TikTok video id, a tweet id), up to 100.
accountIdstringComma-separated account ids, up to 25.
metricsstringComma-separated metric names from the catalog. Defaults to every metric.
groupBystringComma-separated groupings from the catalog, at most 2.
fromDatestringFirst day, inclusive (YYYY-MM-DD, UTC).
toDatestringLast day, inclusive (YYYY-MM-DD, UTC).
platformstringOnly with profileId. One of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, whatsapp, discord, slack.
granularitystringday reads one post. One of: total, day.
originstringLists only. Defaults to all. One of: all, creatoros, external.
sortstringA sort from the catalog, such as published-desc or likes-desc.
includestringComma-separated includes from the catalog.
changedSincestringnow (no rows, the starting cursor) or the previous pagination.nextCursor: one row per post whose metrics changed since, oldest first, across every account the key reads. Narrow with profileId and platform. Changes are kept 7 days; cursors older than 6 days are refused.
limitintegerRows per page, 50 by default, 100 at most.
cursorstringpagination.nextCursor of the previous page, sent with the same query.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/posts" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
"string"
],
"pagination": {
"nextCursor": "string",
"hasMore": true
},
"meta": {
"entity": "string",
"granularity": "total",
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"missingIds": [
"string"
],
"total": "string",
"metricsSample": {
"posts": 0,
"limit": 0
},
"stale": true,
"staleSince": "string"
}
}Read follower and post totals per account, platform or scope over time
/v1/metrics/accountsWorks on: Every network
Query parameters
accountIdstringComma-separated account ids, up to 25.
metricsstringComma-separated metric names from the catalog. Defaults to every metric.
groupBystringComma-separated groupings from the catalog, at most 2.
fromDatestringFirst day, inclusive (YYYY-MM-DD, UTC).
toDatestringLast day, inclusive (YYYY-MM-DD, UTC).
platformstringOnly with profileId. One of: tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, whatsapp, discord, slack.
granularitystringOne of: total, day, week, month.
attributionstringOne of: publish, received.
limitintegerRows per page, 50 by default, 100 at most.
cursorstringpagination.nextCursor of the previous page, sent with the same query.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/accounts" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
{
"date": "2026-10-10T00:00:00.000Z",
"accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
"platform": "social",
"username": "string",
"metrics": {}
}
],
"pagination": {
"nextCursor": "string",
"hasMore": true
},
"meta": {
"entity": "string",
"granularity": "total",
"groupBy": "account",
"attribution": "publish",
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"stale": true,
"staleSince": "string"
}
}Read live account or post insights from the platform
/v1/metrics/insightsWorks on: Every network
Query parameters
accountIdstringrequiredOne account id.
metricsstringComma-separated metric names (up to 25). Defaults to the platform's default metrics. GET /v1/metrics/catalog?entity=insights&platform=... lists them.
platformPostIdstringOne post of the account, by its platform id: answers the post's live insights instead of the account's.
granularitystringDefaults to total; groupBy=hour answers per day. One of: total, day.
groupBystringdemographic: audience segments (age, gender, country...). hour: Instagram followers online per day and hour, last 30 days. keyword: Google Business search keywords per month. query, page, country, device: Google Search Console, combined with commas (groupBy=query,country).
breakdownstringWith groupBy=demographic: comma-separated segments. Defaults to the platform's default segments.
timeframestringInstagram demographics only. Defaults to this_month. One of: this_week, this_month.
cursorstringWith groupBy=keyword or a Search Console account: pagination.nextCursor of the previous page, sent with the same query.
limitintegerSearch Console accounts only: rows per page. Defaults to 1,000.
includestringWith platformPostId on YouTube: retentionCurve adds the audience retention curve.
fromDatestringFirst day, inclusive (YYYY-MM-DD, UTC). Defaults to 30 days before toDate. The window is at most 541 days.
toDatestringLast day, inclusive (YYYY-MM-DD, UTC). Defaults to today.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/insights?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
{
"date": "2026-10-10T00:00:00.000Z",
"breakdown": "string",
"dimension": "string",
"dimensionId": "string",
"dimensions": {},
"metrics": {}
}
],
"pagination": {
"nextCursor": "string",
"hasMore": true
},
"meta": {
"entity": "string",
"accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
"platformPostId": "string",
"platform": "social",
"granularity": "total",
"groupBy": "string",
"timeframe": "this_week",
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"unavailableMetrics": [
{
"metric": "string",
"reason": "string",
"message": "string"
}
],
"units": {},
"dataDelay": "string",
"provisionalSince": "string",
"stale": true
},
"retentionCurve": {
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"provisionalSince": "string",
"durationSeconds": 0,
"segmentMetricsAvailable": true,
"points": [
{
"elapsedVideoTimeRatio": 0,
"audienceWatchRatio": 0,
"relativeRetentionPerformance": 0,
"startedWatching": 0,
"stoppedWatching": 0,
"totalSegmentImpressions": 0
}
]
}
}Read message volume and response times
/v1/metrics/inboxWorks on: Every network
Query parameters
conversationIdstringComma-separated conversation ids (Creator OS or platform), up to 25: one row per conversation.
accountIdstringComma-separated account ids, up to 25.
metricsstringComma-separated metric names from the catalog. Defaults to the counts; response times only when named.
groupBystringComma-separated groupings from the catalog, at most 2: account, conversation, platform, source, hourOfWeek, responseTimeBucket.
fromDatestringFirst day, inclusive (YYYY-MM-DD, UTC). Defaults to 30 days before toDate. The window is at most 90 days.
toDatestringLast day, inclusive (YYYY-MM-DD, UTC). Defaults to today.
platformstringA messaging platform, such as instagram or whatsapp.
sourcestringOnly messages sent from this source, such as api or broadcast. Not with response time metrics.
granularitystringOne of: total, day, week.
sortstringA sort from the catalog, such as messages-desc. With granularity=total.
includestringComma-separated includes from the catalog: account, conversation, total.
limitintegerRows returned with groupBy=account (10 by default, 100 at most) or groupBy=conversation (50 by default, 1,000 at most).
cursorstringWith groupBy=conversation: pagination.nextCursor of the previous page.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/inbox" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
{
"date": "2026-10-10T00:00:00.000Z",
"accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
"platform": "social",
"source": "string",
"dayOfWeek": 0,
"hour": 0,
"responseTimeBucket": {
"label": "string",
"lowerSeconds": 0,
"upperSeconds": 0
},
"account": {
"username": "string",
"displayName": "string"
},
"conversationId": "conv_M4nB7vC1xZ9lK3jH6gF2dS8aP5oI0uY7tR4eW1qQ6",
"firstMessageAt": "2026-10-10T00:00:00.000Z",
"lastMessageAt": "2026-10-10T00:00:00.000Z",
"conversation": {
"platformConversationId": "string",
"participantName": "string",
"participantUsername": "string",
"participantPicture": "string",
"lastMessage": "string"
},
"metrics": {}
}
],
"pagination": {
"nextCursor": "string",
"hasMore": true
},
"meta": {
"entity": "string",
"granularity": "total",
"groupBy": [
"string"
],
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"total": 0,
"totalIsCapped": true,
"stale": true,
"staleSince": "string"
}
}Read ad metrics by id, or one ad day by day with breakdowns
/v1/metrics/adsWorks on: Every network
Query parameters
adIdstringrequiredComma-separated Creator OS ad ids, up to 100.
granularitystringday reads one ad, one point per day. One of: total, day.
fromDatestringWithout fromDate and toDate, the last 90 days.
toDatestringLast day, inclusive (YYYY-MM-DD, UTC).
breakdownsstringComma-separated breakdowns, read live from the platform. One ad only.
attributionWindowsstringMeta attribution windows for the breakdowns, comma-separated.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/ads?adId=%3CadId%3E" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
{
"adId": "string",
"name": "string",
"platform": "social",
"status": "string",
"currency": "string",
"summary": {
"spend": 0,
"impressions": 0,
"reach": 0,
"clicks": 0,
"engagement": 0,
"ctr": 0,
"cpc": 0,
"cpm": 0,
"conversions": 0,
"allConversions": 0,
"costPerConversion": 0,
"actions": {},
"actionValues": {},
"purchaseValue": 0,
"roas": 0,
"costPerAction": {},
"outboundClicks": 0,
"outboundClicksCtr": 0,
"inlineLinkClicks": 0,
"inlineLinkClickCtr": 0,
"uniqueClicks": 0,
"uniqueCtr": 0,
"funnel": {},
"engagementBreakdown": {},
"videoPlayActions": 0,
"video30SecWatchedActions": 0,
"videoThruplayWatchedActions": 0,
"videoP25WatchedActions": 0,
"videoP50WatchedActions": 0,
"videoP75WatchedActions": 0,
"videoP95WatchedActions": 0,
"videoP100WatchedActions": 0,
"videoAvgTimeWatchedActions": 0,
"video2SecWatchedActions": 0,
"video6SecWatchedActions": 0,
"video6SecFocusedViews": 0,
"costPerThruplay": 0,
"lastSyncedAt": "2026-10-10T00:00:00.000Z",
"qualityRanking": "string",
"engagementRateRanking": "string",
"conversionRateRanking": "string",
"videoTotalWatchTime": 0
},
"daily": [
{}
],
"breakdowns": {},
"unsupportedBreakdowns": [
"string"
],
"breakdownHints": {},
"breakdownsRange": "string",
"breakdownErrors": [
"string"
],
"breakdownDroppedMetrics": {}
}
],
"meta": {
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"backfillPending": true,
"missingIds": [
"string"
],
"stale": true,
"staleSince": "string"
}
}Read the uploaded results of each campaign over a window
/v1/metrics/campaignsWorks on: Every network
Query parameters
limitintegerRows per page, 50 by default, 100 at most.
cursorstringpagination.nextCursor of the previous page, sent with the same query.
fromDatestringrequiredFirst day, inclusive.
toDatestringrequiredLast day, inclusive. The range is at most 400 days.
campaignIdstringComma-separated platform campaign ids.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/campaigns?fromDate=%3CfromDate%3E&toDate=%3CtoDate%3E" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"data": [
{
"platform": "social",
"adAccountId": "string",
"campaignId": "string",
"results": {}
}
],
"pagination": {
"nextCursor": "string",
"hasMore": true
},
"meta": {
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"stale": true,
"staleSince": "string"
}
}Read the uploaded results summed across ad accounts
/v1/metrics/ad-accountsWorks on: Every network
Query parameters
fromDatestringrequiredFirst day, inclusive.
toDatestringrequiredLast day, inclusive. The range is at most 400 days.
adAccountIdstringComma-separated platform ad account ids. Defaults to every ad account the key sees.
curl "https://creatoros-production-5658.up.railway.app/v1/metrics/ad-accounts?fromDate=%3CfromDate%3E&toDate=%3CtoDate%3E" \
-H "Authorization: Bearer $CREATOROS_API_KEY"{
"results": {},
"meta": {
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z",
"stale": true,
"staleSince": "string"
}
}Run a Meta Marketing API insights query on one ad account
/v1/metrics/platform-queries/meta-adsWorks on: Every network
Body
accountIdstringrequiredThe Creator OS id of the connected Meta ads account.
adAccountIdstringrequiredThe Meta ad account, act_<n>. Read its campaigns, ad sets or ads with level and filtering.
levelstringThe level of each row. Defaults to the ad account.
fieldsstring[]Meta insights fields, such as spend or impressions, up to 100.
breakdownsstring[]Meta breakdowns, up to 5.
actionBreakdownsstring[]An empty array asks Meta for no action breakdown at all.
actionAttributionWindowsstring[]Meta attribution windows, such as 7d_click or 1d_view.
actionReportTimestringimpression, conversion or mixed.
useUnifiedAttributionSettingbooleanUse each ad set's own attribution setting.
filteringobject[]Meta filters of field, operator and value, up to 25.
datePresetstringA Meta date preset, such as last_30d. Not with fromDate and toDate.
fromDatestringFirst day, YYYY-MM-DD, sent with toDate.
toDatestringLast day, YYYY-MM-DD, sent with fromDate.
timeIncrementstringDays per row, 1 to 90, or monthly or all_days.
limitintegerRows per page, up to 500. Defaults to 500.
cursorstringThe pagination.nextCursor of the previous page, unchanged.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/metrics/platform-queries/meta-ads" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
"adAccountId": "string"
}'{
"data": [
"string"
],
"meta": {
"source": "string",
"platform": "social"
},
"pagination": {
"nextCursor": "string",
"hasMore": true
}
}Run a Google Ads Query Language search on one customer
/v1/metrics/platform-queries/google-adsWorks on: Every network
Body
accountIdstringrequiredThe Creator OS id of the connected Google Ads account.
adAccountIdstringThe Google Ads customer to query. Defaults to the connection's own customer.
querystringrequiredA GAQL SELECT statement, up to 10,000 characters. Read only.
cursorstringThe pagination.nextCursor of the previous page, unchanged.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/metrics/platform-queries/google-ads" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
"query": "string"
}'{
"data": [
"string"
],
"meta": {
"source": "string",
"platform": "social"
},
"pagination": {
"nextCursor": "string",
"hasMore": true
}
}Run a TikTok Marketing API report on one advertiser
/v1/metrics/platform-queries/tiktok-adsWorks on: Every network
Body
accountIdstringrequiredThe Creator OS id of the connected TikTok ads account.
adAccountIdstringrequiredThe numeric TikTok advertiser id.
reportTypestringDefaults to BASIC.
dataLevelstringrequiredThe level of each row.
dimensionsstring[]requiredTikTok dimensions, 1 to 4.
metricsstring[]requiredTikTok metrics, up to 100.
filteringobject[]TikTok filters of field, operator and value, up to 25. A filter on an entity finer than dataLevel is refused.
fromDatestringrequiredFirst day, YYYY-MM-DD, inclusive.
toDatestringrequiredLast day, YYYY-MM-DD, inclusive.
pageSizeintegerRows per page, up to 1,000. Defaults to 1,000.
cursorstringThe pagination.nextCursor of the previous page, unchanged.
curl -X POST "https://creatoros-production-5658.up.railway.app/v1/metrics/platform-queries/tiktok-ads" \
-H "Authorization: Bearer $CREATOROS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
"adAccountId": "string",
"dataLevel": "AUCTION_ADVERTISER",
"dimensions": [
"string"
],
"metrics": [
"string"
],
"fromDate": "2026-10-10T00:00:00.000Z",
"toDate": "2026-10-10T00:00:00.000Z"
}'{
"data": [
"string"
],
"meta": {
"source": "string",
"platform": "social"
},
"pagination": {
"nextCursor": "string",
"hasMore": true
}
}