Tracking media

Tracked media is one piece of Instagram content that ClipStake reads on a schedule. Every reading is kept, so the value of the product is the series rather than any single number.

Submit URLs

POST /submissions takes up to 100 canonical Instagram URLs for one connected account.

curl --request POST "https://api.clipstake.com/v1/submissions" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "3f1c9f0a-2f2c-4c0f-9a7d-8a1c0c4e5b21",
    "username": "creator_handle",
    "urls": [
      "https://www.instagram.com/reel/DAbc123XyZ/",
      "https://www.instagram.com/p/DBcd456UvW/"
    ]
  }'

Accepted URL shapes are https://instagram.com or https://www.instagram.com with a /reel/, /reels/, /p/, or /tv/ path. A bare shortcode is not a URL and is rejected.

One result per URL

The request succeeds even when some URLs do not resolve. Read status on each item.

`status`	Meaning
`created`	Now tracked. `submission` carries the row.
`already_tracked`	This project already tracks it. Safe to send again.
`not_found`	Not found in this account’s recent media.

Submitting is idempotent per project and shortcode, so retrying a whole batch never creates duplicates.

Why tracked media can come back `not_found`

ClipStake finds each URL by looking for the post among the connected account’s recent media, up to its 500 most recent posts. Media can therefore be reported not_found when it is older than that window, when it belongs to a different account than the username you sent, or when it was deleted or made private.

Concurrent requests for the same account share one lookup, so the account’s rate limit is spent once. If a lookup is already running and does not finish in time, the request returns 409 conflict with a Retry-After header. Retry once and the warmed result is used.

Errors that fail the whole request

Status	`code`	Cause
402	`quota_exceeded`	The new media would take the workspace past its submission or account limit. The check covers the whole batch, so no media from it is created.
404	`not_found`	No connected account with that `username`, or no such `project_id`, in this workspace.
409	`conflict`	The connection for `username` is `needs_reauth` or `revoked`, Instagram rejected the account’s authorization during the lookup, or a lookup for this account is already running. Reconnect the account for the first two.
429	`rate_limited`	Instagram is rate limiting this account. Try again later.

Status lifecycle

`status`	Meaning
`active`	On the schedule. `next_read_at` is the earliest allowed read.
`paused`	You paused it. History is kept and nothing is read.
`unavailable`	The media no longer resolves. `unavailable_reason` says why. Terminal.
`parked`	Reading is on hold for a reason outside this media. See Parked media.
`stopped`	Archived with its project, or explicitly stopped. Resume is explicit.

next_read_at is the earliest moment ClipStake is allowed to read the media. It is not a promise that a read happens at that instant. It is null once the media is no longer read at all.

unavailable media cannot be resumed. It is a verdict about the media, not a state you moved it into, so resuming it would fail again on every cycle forever. The API answers 409 conflict.

A billing hold does not change any status. When a renewal fails and the grace period ends, reads stop but every media keeps its status. Paying the invoice starts reads again, with nothing to resume. See Plans and limits.

Parked media

A media is parked when ClipStake stops reading it for a reason that is not about the media itself. There are two causes:

`parked_reason`	What happened	How it comes back
`token_invalid`	The account’s authorization expired or Instagram rejected it. Every active media on that connection is parked.	Automatically, when you reconnect the account.
`read_failed`	Five reads of this media failed in a row for a reason that was not the media’s fault.	Only when you resume it.

parked_reason is set only while status is parked, and is null in every other status. GET /accounts carries the same field for an account whose tracking_status is parked. Resume a parked media with POST /submissions/{shortcode}/resume. Resuming clears the hold and the failure count, and the media is due at once.

Resuming a parked media while its connection still needs a reconnect returns 409 conflict. Reconnect the account first. The reconnect then resumes that connection’s media for you.

An automatic resume after a reconnect respects your submission capacity. Media that does not fit stays parked until you raise the plan and resume it.

Pause and resume

Pause one media, keeping everything already collected:

curl --request POST "https://api.clipstake.com/v1/submissions/DAbc123XyZ/pause" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"project_id": "3f1c9f0a-2f2c-4c0f-9a7d-8a1c0c4e5b21"}'

Or act on a whole project with POST /submissions/pause and POST /submissions/resume. Both take project_id and return how many rows they affected. A resume also returns left_paused: rows it could not admit because the workspace is at its submission limit. The bulk resume acts on paused and stopped media only. It does not resume parked media. Resume those one at a time, or reconnect the account. Resumed media is due at once. Views are a running total, so the first reading after a pause picks up the current figure. The gap in the series is real and stays visible. It is never backfilled.

Reads happen on a fixed UTC schedule. A media read every 4 hours is read at 00:00, 04:00, 08:00 and so on, UTC. A bulk resume puts each row on the next slot of that schedule, not at the moment of the resume.

The literal shortcodes pause and resume are reserved, so the project-wide routes can never be read as a shortcode.

Reading the data

GET /submissions lists tracked media in a project. It filters on status, external_user_id, and username, and pages with limit and cursor. GET /submissions/{shortcode}/stats returns the time series: one point per reading, with captured_at, the metrics, and watch time where Instagram reports it.

`null` never means zero

Every metric is nullable. null means Instagram did not report the metric for that media. A 0 is a real reading. Do not coerce one into the other. An account that is not eligible for a metric would become indistinguishable from an account measuring zero.

Deleting

There is no delete endpoint, and that is deliberate. The old delete only changed a status, so it was an irreversible pause with no other effect. Pause stops reads and keeps history, and the status filter on GET /submissions covers list hygiene.

Getting Started

Guides

Developer Guides

API Reference

Submit URLs

One result per URL

Why tracked media can come back `not_found`

Errors that fail the whole request

Status lifecycle

Parked media

Pause and resume

Reading the data

`null` never means zero

Deleting

​Submit URLs

​One result per URL

​Why tracked media can come back not_found

​Errors that fail the whole request

​Status lifecycle

​Parked media

​Pause and resume

​Reading the data

​null never means zero

​Deleting

Submit URLs

One result per URL

Why tracked media can come back `not_found`

Errors that fail the whole request

Status lifecycle

Parked media

Pause and resume

Reading the data

`null` never means zero

Deleting