Tracking media

Create tracked media

POST /instagram/submissions, POST /x/submissions and POST /youtube/submissions accept 1 to 100 items.

{
  "project_id": "prj_5f9c0a1b2c3d4e5f60718293",
  "account_id": "acct_3f9c0a1b2c3d4e5f60718293",
  "items": [
    {
      "url": "https://www.instagram.com/p/C9x4AbCdEfG/",
      "metadata": { "campaign": "fall" }
    }
  ]
}

account_id must be an account of the path’s platform. Every URL must be a URL of that platform. Each result contains the input url, an open-string status, and a nullable submission. Known result statuses are created, already_tracked, not_found, unsupported_url, platform_mismatch, not_owned, and not_video. The last two apply only to X and YouTube. Clients must accept new statuses. Retrying is safe. already_tracked returns the existing object and does not change its metadata.

Cadence, dates and geo

You can also send these fields. They apply to every item in the request.

Field	Meaning
`cadence_hours`	How often we read each tracked media: 1, 2, 3, 4, 6, 8 or 12. The default is the project’s cadence.
`start_at`	When tracking starts. The default is now.
`end_at`	When tracking ends. It must be in the future and after `start_at`.
`geo`	Collect audience data. Instagram and YouTube only. The default is the project’s setting, which is on for new projects. Send `geo: false` to turn it off.

The response has an estimate of the credits that one tracked media uses. See Credits and limits for the prices. PATCH /{platform}/submissions/{submission_id} can change metadata, cadence_hours and end_at, and can turn geo on. You can turn geo off with geo: false until the first read. After the first read, geo: false returns 409 conflict. Geo on X returns 400 invalid_request. A tracked media past its end_at cannot be resumed. Set a later end_at first.

Tracking media on X

POST /x/submissions takes the same body as Instagram:

{
  "project_id": "prj_5f9c0a1b2c3d4e5f60718293",
  "account_id": "acct_7b2e4d6f8a0c1e3a5c7e9b1d",
  "items": [
    {
      "url": "https://x.com/acmestudio/status/1834567890123456789",
      "metadata": { "campaign": "fall" }
    }
  ]
}

account_id must be an X account that connected through an X connect link. An Instagram account ID returns 404.

Accepted URLs

We accept these URL shapes:

https://x.com/<handle>/status/<id>
https://x.com/i/status/<id>
https://x.com/i/web/status/<id>

The twitter.com host also works. The www. and mobile. hosts work for both domains. A URL can end with /photo/1 or /video/1, and it can have a query string. We ignore the handle in the URL. We use only the status ID. The submission’s canonical url is https://x.com/i/status/<id>.

Only the connected account’s videos

We read each URL and check who published it. We accept the URL only when the publisher is the X account that signed in through the connect link.

Status	Meaning
`created`	We now track this URL as tracked media.
`already_tracked`	The project already has this tracked media for this account.
`not_found`	Nothing exists at this URL on X, or we cannot read it.
`unsupported_url`	The URL is not an X status URL.
`platform_mismatch`	The URL belongs to another platform, for example Instagram.
`not_owned`	Another X account published this URL. This status also applies when the project tracks this URL for a different X account.
`not_video`	The URL has no video. We track only videos on X.

media_type is video for every X submission.

Errors on X

Status	Code	Meaning
402	`insufficient_credits`	The workspace has no credits left.
404	`not_found`	We cannot find the project or the X account.
409	`conflict`	The X sign-in for the account is not active. Send the end user through a new connect link.
429	`rate_limited`	We checked too many URLs at once. Try again after a few minutes.
500	`internal_error`	We could not reach X. We created nothing. Try again.

We never accept a URL when we cannot check it.

Tracking media on YouTube

POST /youtube/submissions takes the same body as Instagram:

{
  "project_id": "prj_5f9c0a1b2c3d4e5f60718293",
  "account_id": "acct_3d5f7a9b1c2e4f6a8b0c1d3e",
  "items": [
    {
      "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ",
      "metadata": { "campaign": "fall" }
    }
  ]
}

account_id must be a YouTube account that connected through a YouTube connect link. An Instagram or X account ID returns 404. We track uploaded YouTube media of any length, Shorts included. We do not track a live or upcoming broadcast.

Accepted URLs

We accept these URL shapes:

https://www.youtube.com/watch?v=<id>
https://www.youtube.com/shorts/<id>
https://www.youtube.com/live/<id>
https://www.youtube.com/embed/<id>
https://youtu.be/<id>

The youtube.com and m.youtube.com hosts also work. A URL can have a query string. The ID has 11 characters. The submission’s canonical url is https://www.youtube.com/watch?v=<id>, for a Short too.

Only the connected channel’s tracked media

We read each URL and check which channel published it. We accept the URL only when the channel is the YouTube account that signed in through the connect link.

Status	Meaning
`created`	We now track this URL as tracked media.
`already_tracked`	The project already has this tracked media for this account.
`not_found`	Nothing exists at this URL on YouTube, or it is private.
`unsupported_url`	The URL is not a YouTube URL that we accept.
`platform_mismatch`	The URL belongs to another platform, for example Instagram.
`not_owned`	Another YouTube channel published this URL. This status also applies when the project tracks this URL for a different YouTube account.
`not_video`	The URL is a live or upcoming broadcast. Send it again after the broadcast ends.

media_type is short_video for YouTube tracked media of 180 seconds or less, and video for longer tracked media.

Errors on YouTube

Status	Code	Meaning
402	`insufficient_credits`	The workspace has no credits left.
404	`not_found`	We cannot find the project or the YouTube account.
409	`conflict`	The YouTube sign-in for the account is not active. Send the end user through a new connect link.
429	`rate_limited`	We cannot check YouTube URLs now. Try again after the time in `Retry-After`.
500	`internal_error`	We could not reach YouTube. We created nothing. Try again.

We never accept a URL when we cannot check it.

Submission object

A submission has a sub_ ID, platform, canonical url, platform media ID, media type, and a compact account summary. It also has lifecycle fields, metrics, metadata, and timestamps. media_type is an open string. Known values are short_video, video, image, carousel, and text. The nested account contains id, username, and external_user_id. It does not contain account metadata.

List and read

GET /instagram/submissions, GET /x/submissions and GET /youtube/submissions require project_id. It supports account_id, external_user_id, status, limit, and cursor filters. Use these operations for one item. The X paths start with /x/submissions, and the YouTube paths start with /youtube/submissions.

GET /instagram/submissions/{submission_id}
PATCH /instagram/submissions/{submission_id}
GET /instagram/submissions/{submission_id}/stats
GET /instagram/submissions/{submission_id}/bot-score (Instagram only)
POST /instagram/submissions/{submission_id}/pause
POST /instagram/submissions/{submission_id}/resume

Use a sub_ ID. Do not send project_id to these operations. Pause and resume have no request body.

Lifecycle

Submission status is a closed enum: active, paused, unavailable, parked, or stopped. Reason fields are open strings. Known unavailable reasons include post_not_found, posted_before_professional, token_invalid, no_linked_account, and connection_removed. Known parked reasons are token_invalid, insights_permission_missing, account_not_professional, and read_failed.

Reason	Meaning
`posted_before_professional`	The media was posted before the Instagram account became a Business or Creator account. Instagram keeps no views for it.
`insights_permission_missing`	The creator did not allow access to insights. Every tracked media of the account is held.
`account_not_professional`	The Instagram account was switched to a personal account. Every tracked media of the account is held.
`read_failed`	Reads failed several times in a row. Resume the tracked media to try again.

token_invalid, insights_permission_missing and account_not_professional are about the account, so the account’s connection.reason carries the same value. The tracked media start again by themselves when the creator connects again. Use POST /{platform}/submissions/pause or POST /{platform}/submissions/resume for one project. These bulk operations require project_id. They change only the tracked media of the path’s platform in that project. X tracked media that is deleted on X becomes unavailable with the reason post_not_found. YouTube tracked media that is deleted or made private on YouTube becomes unavailable with the same reason. There is no delete operation. Pause stops reads and keeps history.

Comments and demographics

List items can include comments and demographics. GET /{platform}/submissions/{submission_id} also includes demographics. Comments report their own captured_at. demographics is present only on geo tracked media, and its basis says whose audience it is:

`basis`	Platform	What it describes
`account`	Instagram	The connected account’s audience during the tracked media’s earliest collection window.
`media`	YouTube	The audience of the tracked media itself, from its publish day to the last read.

See Audience and insights. Analytics fields are omitted when analytics access is not enabled. We do not read comments on X or YouTube. comments.captured_at stays null for X and YouTube tracked media.

Metrics on X

We read X tracked media on the cadence you choose, at the same credit price as Instagram tracked media. Geo is not available on X.

Field	Value on X
`views`	The view count that X shows.
`likes`	Likes.
`comments`	Replies.
`shares`	Reposts.
`saves`	Bookmarks.
`extra.quotes`	Quotes.
`reach`	Always `null`.
`total_interactions`	Always `null`.
`avg_watch_time_ms`	Always `null`.
`total_watch_time_ms`	Always `null`.

There is no bot score for X tracked media.

Metrics on YouTube

We read YouTube tracked media on the cadence you choose, at the same credit price as Instagram tracked media. With geo on, we also read the audience of the tracked media itself once a day. See Audience and insights.

Field	Value on YouTube
`views`	The view count that YouTube shows.
`likes`	Likes. `null` when the channel hides the like count.
`comments`	The comment count. `null` when comments are turned off.
`shares`	Always `null`.
`saves`	Always `null`.
`reach`	Always `null`.
`total_interactions`	Always `null`.
`avg_watch_time_ms`	Always `null`.
`total_watch_time_ms`	Always `null`.

extra is empty for YouTube tracked media. There is no bot score for YouTube tracked media.

Getting Started

API Reference

Developer Guides

Create tracked media

Cadence, dates and geo

Tracking media on X

Accepted URLs

Only the connected account’s videos

Errors on X

Tracking media on YouTube

Accepted URLs

Only the connected channel’s tracked media

Errors on YouTube

Submission object

List and read

Lifecycle

Comments and demographics

Metrics on X

Metrics on YouTube

​Create tracked media

​Cadence, dates and geo

​Tracking media on X

​Accepted URLs

​Only the connected account’s videos

​Errors on X

​Tracking media on YouTube

​Accepted URLs

​Only the connected channel’s tracked media

​Errors on YouTube

​Submission object

​List and read

​Lifecycle

​Comments and demographics

​Metrics on X

​Metrics on YouTube

Create tracked media

Cadence, dates and geo

Tracking media on X

Accepted URLs

Only the connected account’s videos

Errors on X

Tracking media on YouTube

Accepted URLs

Only the connected channel’s tracked media

Errors on YouTube

Submission object

List and read

Lifecycle

Comments and demographics

Metrics on X

Metrics on YouTube