Read a video's metric history (GET /v1/videos/{platform}/{id}/snapshots)

GET /v1/videos/{platform}/{id}/snapshots

Views and metrics over time, newest first. A metric is null where its Snapshot marks it unreported; one a Platform never reports can still read 0, such as Instagram and Facebook shares and saves. is_ad/paid_partnership appear where recorded. Shared and kept forever, so history predates your first lookup. A video gets Snapshots only while a lookup, search, Creator Tracker page or Keyword, Hashtag or Sound Sample reads it, so those histories have gaps: a missing day is not a drop. not_found until looked up with GET /v1/videos/{platform}/{id}.

Open in Playground (no API Key needed)

Price

Free.

Parameters

Name	In	Type	Required	Default	Description
`platform`	path	`string` one of `tiktok`, `instagram`, `youtube`, `facebook`	Required	—	Platform the subject lives on.
`id`	path	`string`	Required	—	Platform video id.
`limit`	query	`integer` min 1; max 100	Optional	`25`	Items per page.
`cursor`	query	`string`	Optional	—	Opaque `next_cursor` from the previous page.

Responses

200 OK

{ items, next_cursor }.

object

A page of a list. items holds the page; pass next_cursor back as cursor for the next one.

next_cursor string required nullable Pass back as cursor. Null on the last page.
items array of object required
- at string required When the metrics were read.
- views number required nullable Views at at. Null when the Snapshot marks them unreported.
- metrics object required The public metrics recorded at at.
  views number required nullable Views. Null when the Snapshot marks it unreported.
  likes number required nullable Likes. Null when the Snapshot marks it unreported.
  comments number required nullable Comments. Null when the Snapshot marks it unreported.
  shares number required nullable Shares. Null when the Snapshot marks it unreported.
  saves number required nullable Saves. Null when the Snapshot marks it unreported.
  is_ad boolean nullable The Platform marked the video as an ad at at. Present only when the read recorded ad flags.
  paid_partnership boolean nullable The Platform marked a paid partnership at at. Present only when the read recorded ad flags.
- source string required vendor or backfill.

200 · `{ items, next_cursor }`.

{
  "items": [
    {
      "at": "2026-09-08T09:14:04.219Z",
      "views": 1284000,
      "metrics": {
        "views": 1284000,
        "likes": 98200,
        "comments": 1410,
        "shares": 3020,
        "saves": 7650,
        "is_ad": false,
        "paid_partnership": false
      },
      "source": "vendor"
    },
    {
      "at": "2026-09-07T09:12:58.104Z",
      "views": 912400,
      "metrics": {
        "views": 912400,
        "likes": 70150,
        "comments": 1022,
        "shares": 2210,
        "saves": null
      },
      "source": "vendor"
    }
  ],
  "next_cursor": "eyJpZCI6ImNsdjRxOHoifQ"
}

400 Bad Request

invalid_request for a cursor that is not a next_cursor this API issued. Nothing is charged.

Code: invalid_request. The problem body and every code are on Errors.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.

type string required
title string required
status integer required
code string required one of missing_authorization, invalid_key, key_revoked, key_expired, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, key_scope_insufficient, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, focus_unsupported_kind, not_found, comment_not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, max_credits_exceeded, key_spend_cap_exceeded, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_error Stable machine-readable code.
detail string
errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
- path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
- message string required What is wrong with that field.
request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
action string required The next step, in one sentence.
remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
expired_at string When the key expired. On key_expired.
resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
limit integer The limit that was hit, on the *_limit_exceeded codes.
running integer Runs in flight. On concurrency_limit_exceeded.
active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
count integer Collections held. On collection_limit_exceeded.
balance_credits integer The Balance, in Credits. On insufficient_balance.
required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
max_credits integer The cap the call sent. On max_credits_exceeded.
estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
endpoints array of string The sources that could not answer. On source_unavailable.
endpoint string The source that could not answer. On source_unavailable.
candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
duration_seconds number The video's length. On video_too_long.
max_duration_seconds number The longest video accepted. On video_too_long.
overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
scope string always read_only The key's scope. On key_scope_insufficient.
required string always full The scope the call needs. On key_scope_insufficient.
collection_id string The Collection that already has the name. On collection_name_taken.
collection_kind string The Collection's kind. On collection_kind_mismatch.
kind string The kind that was offered. On collection_kind_mismatch.
run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
reason string A short machine-readable reason, where a code has several.
reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
run object The Run, on a failed Run's body, so its id is kept.
- id string required
- kind string required What was run, e.g. video_lookup.
- status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
- created_at string required RFC 3339.
- completed_at string required nullable Null while the Run is still running.
- charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
- list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
- cached boolean required True when a stored result answered without a fresh fetch.
- progress object What a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
  stage string required one of keywords, searching, filtering, analysing, writing_digest
  keywords integer value at least 0
  searches integer value at least 0
  found integer value at least 0
  judged integer value at least 0
  kept integer value at least 0
  dropped_off_topic integer value at least 0
  dropped_unsure integer value at least 0
  shortlisted integer value at least 0
  analysed integer value at least 0
  updated_at string required
error object The same problem, nested, on a failed Run's body.

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "`cursor` is not a cursor this API issued. Pass back the `next_cursor` from the previous page.",
  "retryable": false,
  "action": "Fix the field named in `detail`, then send the corrected request."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked, key_expired or invalid_token.

Codes: missing_authorization, invalid_key, key_revoked, key_expired, invalid_token. The problem body and every code are on Errors.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.

type string required
title string required
status integer required
code string required one of missing_authorization, invalid_key, key_revoked, key_expired, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, key_scope_insufficient, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, focus_unsupported_kind, not_found, comment_not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, max_credits_exceeded, key_spend_cap_exceeded, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_error Stable machine-readable code.
detail string
errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
- path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
- message string required What is wrong with that field.
request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
action string required The next step, in one sentence.
remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
expired_at string When the key expired. On key_expired.
resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
limit integer The limit that was hit, on the *_limit_exceeded codes.
running integer Runs in flight. On concurrency_limit_exceeded.
active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
count integer Collections held. On collection_limit_exceeded.
balance_credits integer The Balance, in Credits. On insufficient_balance.
required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
max_credits integer The cap the call sent. On max_credits_exceeded.
estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
endpoints array of string The sources that could not answer. On source_unavailable.
endpoint string The source that could not answer. On source_unavailable.
candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
duration_seconds number The video's length. On video_too_long.
max_duration_seconds number The longest video accepted. On video_too_long.
overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
scope string always read_only The key's scope. On key_scope_insufficient.
required string always full The scope the call needs. On key_scope_insufficient.
collection_id string The Collection that already has the name. On collection_name_taken.
collection_kind string The Collection's kind. On collection_kind_mismatch.
kind string The kind that was offered. On collection_kind_mismatch.
run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
reason string A short machine-readable reason, where a code has several.
reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
run object The Run, on a failed Run's body, so its id is kept.
- id string required
- kind string required What was run, e.g. video_lookup.
- status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
- created_at string required RFC 3339.
- completed_at string required nullable Null while the Run is still running.
- charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
- list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
- cached boolean required True when a stored result answered without a fresh fetch.
- progress object What a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
  stage string required one of keywords, searching, filtering, analysing, writing_digest
  keywords integer value at least 0
  searches integer value at least 0
  found integer value at least 0
  judged integer value at least 0
  kept integer value at least 0
  dropped_off_topic integer value at least 0
  dropped_unsure integer value at least 0
  shortlisted integer value at least 0
  analysed integer value at least 0
  updated_at string required
error object The same problem, nested, on a failed Run's body.

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console.",
  "retryable": false,
  "action": "Check the whole key was copied, or create a new key in the console."
}

404 Not Found

not_found — including anything belonging to another Customer.

Code: not_found. The problem body and every code are on Errors.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.

type string required
title string required
status integer required
code string required one of missing_authorization, invalid_key, key_revoked, key_expired, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, key_scope_insufficient, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, focus_unsupported_kind, not_found, comment_not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, max_credits_exceeded, key_spend_cap_exceeded, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_error Stable machine-readable code.
detail string
errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
- path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
- message string required What is wrong with that field.
request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
action string required The next step, in one sentence.
remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
expired_at string When the key expired. On key_expired.
resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
limit integer The limit that was hit, on the *_limit_exceeded codes.
running integer Runs in flight. On concurrency_limit_exceeded.
active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
count integer Collections held. On collection_limit_exceeded.
balance_credits integer The Balance, in Credits. On insufficient_balance.
required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
max_credits integer The cap the call sent. On max_credits_exceeded.
estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
endpoints array of string The sources that could not answer. On source_unavailable.
endpoint string The source that could not answer. On source_unavailable.
candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
duration_seconds number The video's length. On video_too_long.
max_duration_seconds number The longest video accepted. On video_too_long.
overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
scope string always read_only The key's scope. On key_scope_insufficient.
required string always full The scope the call needs. On key_scope_insufficient.
collection_id string The Collection that already has the name. On collection_name_taken.
collection_kind string The Collection's kind. On collection_kind_mismatch.
kind string The kind that was offered. On collection_kind_mismatch.
run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
reason string A short machine-readable reason, where a code has several.
reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
run object The Run, on a failed Run's body, so its id is kept.
- id string required
- kind string required What was run, e.g. video_lookup.
- status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
- created_at string required RFC 3339.
- completed_at string required nullable Null while the Run is still running.
- charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
- list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
- cached boolean required True when a stored result answered without a fresh fetch.
- progress object What a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
  stage string required one of keywords, searching, filtering, analysing, writing_digest
  keywords integer value at least 0
  searches integer value at least 0
  found integer value at least 0
  judged integer value at least 0
  kept integer value at least 0
  dropped_off_topic integer value at least 0
  dropped_unsure integer value at least 0
  shortlisted integer value at least 0
  analysed integer value at least 0
  updated_at string required
error object The same problem, nested, on a failed Run's body.

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such resource for this Customer.",
  "retryable": false,
  "action": "Check the id or handle; list your resources to find the right one."
}

Request samples

Use ShortsIntel to read a video's metric history.

- platform: tiktok
- id: 7300000000000000000
- limit: 25

Tell me what it will cost before you run it, then summarise what you find.

If you don't have ShortsIntel tools, don't guess: read https://www.shortsintel.com/agents.md, follow it to connect, then retry this request.

curl "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000/snapshots?limit=25" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000/snapshots?limit=25",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();

import requests

response = requests.get(
    "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000/snapshots?limit=25",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()

Pagination: Following next_cursor through a list.
Addressing videos and creators: Naming a video, creator, hashtag or sound.
Analysis: What we derive from a video, why it is computed once and reused, and when asking for a refresh is charged as new work.
Scores: Outlier and velocity, how a creator baseline is built, what confidence means, and when a score stops being reported.

Price

Parameters

Responses

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Request samples

Related guides