API resource

Instagram

Instagram-only reads and settings: account insights and demographics, Stories and their insights, licensed audio for Reels, your publishing quota, and the ice-breaker prompts shown when someone opens a DM.

Get Instagram insights

GET/v1/analytics/instagram/account-insights

Works on: Instagram

Returns account-level Instagram insights such as reach, views, accounts engaged, and total interactions. These metrics reflect the entire account's performance across all content surfaces (feed, stories, explore, profile), and are fundamentally different from post-level metrics. Data may be delayed up to 48 hours. Max 90 days, defaults to last 30 days. Requires analytics access on your plan.

Query parameters

accountIdstringrequired

The account id for the Instagram account

metricsstring

Comma-separated list of metrics. Defaults to "reach,views,accounts_engaged,total_interactions". Valid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares, replies, reposts, follows_and_unfollows, profile_links_taps. Note: only "reach" supports metricType=time_series.

fromDatestring

Start date (YYYY-MM-DD). Defaults to 30 days ago.

toDatestring

End date (YYYY-MM-DD). Defaults to today.

sincestring

Alias of fromDate, kept for existing callers

untilstring

Alias of toDate, kept for existing callers

metricTypestring

"total_value" (default) returns aggregated totals and supports breakdowns. "time_series" returns daily values but only works with the "reach" metric.

breakdownstring

Breakdown dimension (only valid with metricType=total_value). Valid values depend on the metric: media_product_type, follow_type, follower_type, contact_button_type.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/instagram/account-insights?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
  "platform": "instagram",
  "dateRange": {
    "since": "string",
    "until": "string"
  },
  "metricType": "time_series",
  "breakdown": "string",
  "metrics": {},
  "unavailableMetrics": [
    {
      "metric": "string",
      "reason": "not_enrolled",
      "message": "string"
    }
  ],
  "dataDelay": "Data may be delayed up to 48 hours"
}

Get Instagram demographics

GET/v1/analytics/instagram/demographics

Works on: Instagram

Returns audience demographic insights for an Instagram account, broken down by age, city, country, and/or gender. Requires at least 100 followers. Returns top 45 entries per dimension. Data may be delayed up to 48 hours. Requires analytics access on your plan.

Query parameters

accountIdstringrequired

The account id for the Instagram account

metricstring

"follower_demographics" for follower audience data, or "engaged_audience_demographics" for engaged viewers.

breakdownstring

Comma-separated list of demographic dimensions: age, city, country, gender. Defaults to all four if omitted.

timeframestring

Time period for demographic data. Defaults to "this_month".

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/instagram/demographics?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
  "platform": "instagram",
  "metric": "follower_demographics",
  "timeframe": "this_week",
  "demographics": {},
  "note": "Demographics show top 45 entries per dimension. Requires 100+ followers."
}

Get Instagram follower history

GET/v1/analytics/instagram/follower-history

Works on: Instagram

Returns a daily running Instagram follower count time series, served from Creator OS's cross-platform daily snapshotter. Exists because Meta removed follower_count from the /insights endpoint in Graph API v22+ and never exposed a historical daily series via any public API. Response envelope matches /v1/analytics/instagram/account-insights so the same client handling works. Max 89 days, defaults to last 30 days. Requires analytics access on your plan.

Query parameters

accountIdstringrequired

The account id for the Instagram account.

metricsstring

Comma-separated list. Defaults to "follower_count,followers_gained,followers_lost". - follower_count : per-day raw follower count - followers_gained : sum of positive daily deltas - followers_lost : sum of absolute negative daily deltas

fromDatestring

Start date (YYYY-MM-DD). Defaults to 30 days ago.

toDatestring

End date (YYYY-MM-DD). Defaults to today.

sincestring

Alias of fromDate, kept for existing callers

untilstring

Alias of toDate, kept for existing callers

metricTypestring

"total_value" returns aggregated totals (latest for follower_count, sum for gained/lost). "time_series" returns per-day values in the "values" array.

curl "https://creatoros-production-5658.up.railway.app/v1/analytics/instagram/follower-history?accountId=acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "success": true,
  "accountId": "acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r",
  "platform": "instagram",
  "dateRange": {
    "since": "string",
    "until": "string"
  },
  "metricType": "time_series",
  "breakdown": "string",
  "metrics": {},
  "unavailableMetrics": [
    {
      "metric": "string",
      "reason": "not_enrolled",
      "message": "string"
    }
  ],
  "dataDelay": "Data may be delayed up to 48 hours"
}

List active Instagram stories

GET/v1/accounts/{accountId}/instagram/stories

Works on: Instagram

Returns the IG Business/Creator account's currently-active stories. Meta keeps stories live for 24h; expired stories are not returned. Limitations propagated from Meta (these are NOT bugs): - 24h window only - Live videos excluded - Reshared stories not returned - `mediaUrl` may be null if Meta flagged the story for copyright - `caption`, `likeCount`, `commentsCount` do not apply to story media

Path parameters

accountIdstringrequired

The Instagram account ID

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

Response 200

{
  "data": [
    {
      "id": "string",
      "mediaType": "string",
      "mediaProductType": "string",
      "mediaUrl": "string",
      "permalink": "string",
      "thumbnailUrl": "string",
      "timestamp": "string"
    }
  ]
}

Get Instagram story insights

GET/v1/accounts/{accountId}/instagram/stories/{storyId}/insights

Works on: Instagram

Returns metrics for a single story. The `source` field discriminates between three states: - `live`: fetched from Meta in real time (story is still active) - `cached`: fetched from a persisted `story_insights` webhook payload (story has expired but we received its final-state metrics from Meta) - `unavailable`: story has expired and we never received its webhook payload (for example, the account connected after the story expired) Meta can report an expired story as an empty successful result rather than an error, so an expired story resolves to `cached` or `unavailable` even though the upstream request itself succeeded. Field semantics follow Meta's API.

Path parameters

accountIdstringrequired

The Instagram account ID

storyIdstringrequired

The Instagram media ID of the story.

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

Response 200

{
  "data": {
    "source": "live",
    "metrics": {
      "views": 0,
      "reach": 0,
      "replies": 0,
      "shares": 0,
      "navigation": 0,
      "tapsForward": 0,
      "tapsBack": 0,
      "exits": 0,
      "swipesForward": 0,
      "profileVisits": 0,
      "follows": 0,
      "reposts": 0,
      "totalInteractions": 0
    }
  }
}

Search Instagram audio

GET/v1/accounts/{accountId}/instagram/audio

Works on: Instagram

Search Instagram's audio catalog (licensed music or original sounds), or list what is currently trending by omitting `q`. Returns up to ~30 assets; Meta exposes no pagination on this edge. Pass the returned `audioId` as `platformSpecificData.audioConfiguration.audioId` when creating a Reel to publish it with that track. Requires an Instagram account connected via **Facebook Login**. Meta hosts this catalog on graph.facebook.com only, so accounts connected with classic Instagram Login receive a 400 (`instagram_audio_requires_facebook_login`) and must be reconnected choosing the Facebook option.

Path parameters

accountIdstringrequired

The ID of the Instagram account

Query parameters

audioTypestringrequired

Catalog to search: licensed music or original sounds from Reels.

qstring

Search keywords. Omit to get the current trending list.

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/instagram/audio?audioType=%3CaudioType%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "audio": []
}

Get Instagram audio metadata

GET/v1/accounts/{accountId}/instagram/audio/{audioId}

Works on: Instagram

Fetch one audio asset's metadata by ID. Use it to re-validate a stored `audioId` before a scheduled Reel publishes, or to refresh the preview `downloadUrl` (Meta expires preview URLs after roughly 1.5 days). Same connection requirement as the search endpoint: Facebook-Login Instagram accounts only.

Path parameters

accountIdstringrequired

The ID of the Instagram account

audioIdstringrequired

Instagram audio asset ID

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

Response 200

{
  "audio": "string"
}

Get Instagram publishing limit

GET/v1/accounts/{accountId}/instagram/publishing-limit

Works on: Instagram

Returns the account's remaining content-publishing quota for Instagram's rolling 24-hour window, so you can pace publishing and warn before the cap is reached. `quotaUsage` counts containers published since the start of the window. Always compare against the returned `quotaTotal` rather than hardcoding a number: Meta's prose documentation and the live API disagree on the value, and the live value is authoritative.

Path parameters

accountIdstringrequired

The ID of the Instagram account

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

Response 200

{
  "quotaUsage": 0,
  "quotaTotal": 0,
  "quotaDurationSeconds": 0
}

Get IG ice breakers

GET/v1/accounts/{accountId}/instagram-ice-breakers

Works on: Instagram

Get the ice breaker configuration for an Instagram account.

Path parameters

accountIdstringrequired

No description

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

Response 200

{
  "data": []
}

Set IG ice breakers

PUT/v1/accounts/{accountId}/instagram-ice-breakers

Works on: Instagram

Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.

Path parameters

accountIdstringrequired

No description

Body

ice_breakersarrayrequired

No description

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_uwsum2TkX6QB7M2BWX_F2kYykNTaWuC3V2Spge_Xm4r/instagram-ice-breakers" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ice_breakers": "<ice_breakers>"
  }'

Response 200

{
  "success": true
}

Delete IG ice breakers

DELETE/v1/accounts/{accountId}/instagram-ice-breakers

Works on: Instagram

Removes the ice breaker questions from an Instagram account's Messenger experience.

Path parameters

accountIdstringrequired

No description

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

Response 200

{
  "success": true
}

PreviousPost options by network NextTikTok