Filter a breakdown's videos (GET /v1/breakdowns/{id}/videos)

GET /v1/breakdowns/{id}/videos

A Breakdown's Videos, answered as GET /v1/research/{id}/videos answers them: same filters, sort, paging and as_of, lift basis creator_median.

Open in Playground (no API Key needed)

Price

Free, forever, filtered or not. Collection is the only thing charged.

Parameters

Name	In	Type	Required	Default	Description
`id`	path	`string`	Required	—	Breakdown id — the id of its Run.
`min_views`	query	`integer` min 0	Optional	—	Keep videos with at least this many views. A video with no view count is excluded rather than assumed to be at zero.
`max_views`	query	`integer` min 0	Optional	—	Keep videos with at most this many views.
`platforms`	query	`string`	Optional	—	Comma-separated, or repeated, each one of `tiktok`, `instagram`, `youtube`, `facebook`; any other value is a 400. Omit for every platform the research covered. There is no per-video `region`: a research collects under one region.
`start_date`	query	`string`	Optional	—	Keep videos posted at or after this ISO 8601 date (`2026-01-01`, midnight UTC) or date-time with `Z` or an explicit offset (`2026-01-01T00:00:00Z`). A video with no posted date is excluded.
`end_date`	query	`string`	Optional	—	Keep videos posted at or before this ISO 8601 date or date-time (a date-time needs `Z` or an explicit offset). A date alone (`2026-01-31`) includes the whole of that UTC day; a date-time is the exact instant. A video with no posted date is excluded.
`creator`	query	`string`	Optional	—	A creator id or handle, with or without the `@`, matched case-insensitively.
`hashtag`	query	`string`	Optional	—	A single hashtag, with or without the leading `#`.
`sound`	query	`string`	Optional	—	A sound id, as `sound.id` carries it.
`order_by`	query	`string` one of `rank`, `outlier`, `views`, `posted_at`	Optional	`rank`	`rank` is the research's own ordering — outlier, then views — which is what the digest was written from. It is that frozen order under either `as_of`: `latest` does not re-rank, so use `order_by=outlier` for the order over the numbers actually served. Ties break on `platform:id`, so paging never drops or repeats a video.
`sort`	query	`string` one of `asc`, `desc`	Optional	`desc`	Direction. `desc` is best-first for every `order_by`. Videos missing the value being sorted on come last in both directions: unknown is not the same as smallest.
`limit`	query	`integer` min 1; max 100	Optional	`25`	Videos per page. Over the maximum, or negative, is a 400 rather than a silent clamp.
`offset`	query	`integer` min 0	Optional	`0`	Videos to skip. Past the end returns an empty page with the true `total`.
`as_of`	query	`string` one of `run`, `latest`	Optional	`run`	Which snapshots to read. `run` (the default) is what the research saw, frozen, so the list agrees with the digest. `latest` serves the newest snapshot this API holds for each video, and filters and ordering run over those numbers (a `min_` filter means "over that many now"); `outlier` and `outlier_p90` are recomputed against the research's baseline, `velocity` and `percentile` stay as measured. `latest` is uneven until you refresh: a video is as fresh as the last time anything looked at it, else it keeps the research numbers; `POST /research/{id}/refresh` updates its refreshable videos (TikTok today). Every response states its basis.

Responses

200 OK

{ items, total, limit, offset, as_of }.

object

A page of one research read. items holds the page; it pages with limit and offset over a frozen set.

total integer required Rows matching the filters, before limit and offset.
limit integer required
offset integer required
as_of string required one of run, latest Which snapshots the numbers come from: run is what the research itself saw, frozen, so a read always agrees with the digest; latest is the newest snapshot this API holds for each video.
items array of object required
- platform string required
- id string required
- url string required nullable
- description string required
- posted_at string required nullable
- duration_seconds number required nullable
- thumbnail_url string required nullable
- hashtags array of string required
- sound object required nullable
  id string required
  title string required nullable
  author string required nullable Who made the sound, as the platform names them. Null when the platform did not say (Facebook never does).
  is_original boolean required nullable True for the creator's own audio (a voiceover or original sound), false for a catalogue or library track. Null when the platform did not say, never false for unknown.
- creator object required nullable
  id string required
  handle string required nullable
  name string required
  follower_count number required nullable
  avatar_url string required nullable Our archived copy when there is one, else the platform's URL, which may be signed and expire. Download it rather than storing the link.
  verified boolean required nullable The creator's verified badge, from their latest profile read, else from this video's read. Null when neither reported it.
- region string required nullable Where the video was posted, as the platform reports it (a country code on TikTok). Null when not reported.
- language string required nullable Platform-declared caption language, e.g. en (TikTok). Null when not reported.
- title string required nullable The video's own title (YouTube, Facebook). description still starts with it on YouTube, as before. Null when the platform shows none or did not report it.
- commerce object required nullable Platform-declared commerce: what the Platform itself says, never inferred from the content. Each flag is null when not reported, never false. The object is null when nothing in it was reported.
  is_ad boolean required nullable The Platform marks the video as an ad (TikTok, Instagram).
  paid_partnership boolean required nullable The Platform marks a paid partnership (TikTok, Instagram; on YouTube, its "Includes paid promotion" label).
  affiliate boolean required nullable The Platform marks affiliate content (Instagram).
  shop_url string required nullable The product link the video carries (TikTok Shop).
  anchors array of object required The links the video carries under its caption (an editing template, a product, a place). Empty when none were reported.
  kind string required The Platform's own anchor type id, e.g. 54.
  label string required What the anchor shows, e.g. CapCut · Editing made easy.
- people object required nullable Platform-declared people: accounts the Video itself mentions or names. On TikTok mentions are the caption's mentions; on Instagram they are the users the Video tags, then the accounts its caption names. Null when it named none.
  mentions array of string required Handles the caption mentions (lowercased).
  collaborators array of object required Co-authors the Platform names on the Video (an Instagram collab, a Facebook collaborator).
  handle string required nullable
  name string required nullable
- location object required nullable The place the Video names (Instagram). Null when it named none or the read did not say.
  id string required nullable The Platform's own place id. Null when not sent.
  name string required The place, e.g. Central Park, New York.
- topics object required nullable Platform-declared topics. Null when the Platform reported none.
  keywords array of string required The creator's own tags (YouTube).
  genre string required nullable The Platform's category, e.g. Education (YouTube).
  labels array of string required The Platform's own category labels (TikTok).
- chapters array of object required nullable The description's chapters, in order (YouTube). Null when the video has none or they were not reported.
  title string required
  start_seconds number required Where the chapter starts, in seconds from the start.
- ai_generated boolean required nullable The Platform labels the video AI-generated (TikTok). Null when not reported.
- snapshot object required nullable
  at string required
  views number required
  likes number required
  comments number required
  shares number required
  saves number required
- scores object required nullable Null when the creator has no baseline yet.
  outlier number required nullable Views over the creator's median views.
  outlier_p90 number required nullable
  percentile number required nullable Where this video sits in the creator's own sample, 0-100.
  velocity object required nullable
  views_per_hour number required
  window string required
  reason string required nullable always aged_out aged_out when the video is over 30 days old and Scores are null.
  baseline object required The yardstick every Score on this creator is measured against.
  median_views number required
  p90_views number required
  engagement_rate number required nullable
  posts_per_week number required nullable
  sample integer required
  confidence string required one of high, low
  source string required one of videos, follower_tier
  computed_at string required nullable
  stale boolean required True past 7 days; the next lookup refreshes it.
- coverage string always partial Present only where the platform's index is best-effort.
- rank integer required Position in the research's own ranking, best first from 0 — outlier, then views.
- item_id string required nullable The run item this video was delivered by, if still present.
- cached boolean required Whether the analysis was already stored rather than paid for.

200 · `{ items, total, limit, offset, as_of }`.

{
  "items": [
    {
      "platform": "tiktok",
      "id": "7300000000000000000",
      "url": "https://www.tiktok.com/@someone/video/7300000000000000000",
      "description": "3 minutes at 4°C every morning for 30 days. Here is what actually changed. #coldplunge #recovery",
      "posted_at": "2026-09-05T06:32:11.000Z",
      "duration_seconds": 41,
      "thumbnail_url": "https://p16-sign.tiktokcdn.com/obj/tos-cover-7300000000000000000.jpeg",
      "hashtags": [
        "coldplunge",
        "recovery",
        "morningroutine"
      ],
      "sound": {
        "id": "7180000000000000000",
        "title": "original sound - someone",
        "author": "someone",
        "is_original": true
      },
      "creator": {
        "id": "cre_9d4b2a7f1c",
        "handle": "someone",
        "name": "Someone",
        "follower_count": 184300,
        "avatar_url": "https://p16-sign.tiktokcdn.com/obj/tos-avatar-someone.jpeg",
        "verified": false
      },
      "region": "US",
      "language": "en",
      "title": null,
      "commerce": {
        "is_ad": false,
        "paid_partnership": null,
        "affiliate": null,
        "shop_url": null,
        "anchors": [
          {
            "kind": "54",
            "label": "CapCut · Editing made easy"
          }
        ]
      },
      "people": {
        "mentions": [
          "coldplungeco"
        ],
        "collaborators": []
      },
      "location": null,
      "topics": {
        "keywords": [],
        "genre": null,
        "labels": [
          "Fitness",
          "Health"
        ]
      },
      "chapters": null,
      "ai_generated": false,
      "snapshot": {
        "at": "2026-09-08T09:14:04.219Z",
        "views": 1284000,
        "likes": 143200,
        "comments": 2810,
        "shares": 9040,
        "saves": 21600
      },
      "scores": {
        "outlier": 4.21,
        "outlier_p90": 1.6,
        "percentile": 95,
        "velocity": {
          "views_per_hour": 6698.6,
          "window": "snapshot"
        },
        "reason": null,
        "baseline": {
          "median_views": 305000,
          "p90_views": 802000,
          "engagement_rate": 0.1342,
          "posts_per_week": 4.1,
          "sample": 20,
          "confidence": "high",
          "source": "videos",
          "computed_at": "2026-09-08T09:14:03.902Z",
          "stale": false
        }
      },
      "rank": 0,
      "item_id": "ri_5c30f18ab4",
      "cached": true
    },
    {
      "platform": "tiktok",
      "id": "7300000000000000042",
      "url": "https://www.tiktok.com/@anotherone/video/7300000000000000042",
      "description": "I tried cold plunging before every workout for a week. #coldplunge",
      "posted_at": "2026-09-06T13:04:52.000Z",
      "duration_seconds": 28,
      "thumbnail_url": "https://p16-sign.tiktokcdn.com/obj/tos-cover-7300000000000000042.jpeg",
      "hashtags": [
        "coldplunge",
        "gym"
      ],
      "sound": {
        "id": "7180000000000000099",
        "title": "Winter Air",
        "author": "Northbound",
        "is_original": false
      },
      "creator": {
        "id": "cre_1a77c0b3de",
        "handle": "anotherone",
        "name": "Another One",
        "follower_count": 21400,
        "avatar_url": null,
        "verified": null
      },
      "region": "GB",
      "language": "en",
      "title": null,
      "commerce": {
        "is_ad": false,
        "paid_partnership": null,
        "affiliate": null,
        "shop_url": null,
        "anchors": []
      },
      "people": null,
      "location": null,
      "topics": null,
      "chapters": null,
      "ai_generated": null,
      "snapshot": {
        "at": "2026-09-08T09:14:04.219Z",
        "views": 96200,
        "likes": 8140,
        "comments": 212,
        "shares": 401,
        "saves": 1180
      },
      "scores": null,
      "rank": 1,
      "item_id": "ri_5c30f18ab5",
      "cached": false
    }
  ],
  "total": 48,
  "limit": 25,
  "offset": 0,
  "as_of": "run"
}

400 Bad Request

invalid_request — an unknown platform, a min_views or max_views that is not a non-negative integer, an unparseable date, an unknown order_by, sort or as_of, a limit outside 1 to 100, or a negative or non-integer offset.

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: its stage and the counts known by then, such as 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, reading_creators, filtering, analysing, writing_digest
  keywords integer value at least 0
  creators integer value at least 0
  creators_read 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": "`limit` must be an integer between 1 and 100, and `offset` a non-negative integer.",
  "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: its stage and the counts known by then, such as 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, reading_creators, filtering, analysing, writing_digest
  keywords integer value at least 0
  creators integer value at least 0
  creators_read 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.

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: its stage and the counts known by then, such as 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, reading_creators, filtering, analysing, writing_digest
  keywords integer value at least 0
  creators integer value at least 0
  creators_read 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 research with that id for this Customer.",
  "retryable": false,
  "action": "Check the id or handle; list your resources to find the right one."
}

409 Conflict

run_not_ready — the research is still running, or failed with nothing to serve. If it is still running, poll GET /v1/runs/{id} and read again once it settles; a failed research never becomes readable.

Code: run_not_ready. 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: its stage and the counts known by then, such as 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, reading_creators, filtering, analysing, writing_digest
  keywords integer value at least 0
  creators integer value at least 0
  creators_read 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.

409 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/run_not_ready",
  "title": "Run not ready",
  "status": 409,
  "code": "run_not_ready",
  "detail": "Research `run_c07a41bb92` is still running. Poll GET /v1/runs/run_c07a41bb92 until it reaches a terminal status.",
  "retryable": true,
  "action": "Poll the Run until it settles, then read again. If it failed, start a new Run."
}

Request samples

Use ShortsIntel to filter a breakdown's videos.

- id: id_example
- platforms: tiktok,youtube
- start_date: 2026-01-01
- end_date: 2026-01-31
- order_by: rank
- sort: desc
- limit: 25
- offset: 0
- as_of: run

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/breakdowns/id_example/videos?platforms=tiktok%2Cyoutube&start_date=2026-01-01&end_date=2026-01-31&order_by=rank&sort=desc&limit=25&offset=0&as_of=run" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

const response = await fetch(
  "https://www.shortsintel.com/v1/breakdowns/id_example/videos?platforms=tiktok%2Cyoutube&start_date=2026-01-01&end_date=2026-01-31&order_by=rank&sort=desc&limit=25&offset=0&as_of=run",
  {
    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/breakdowns/id_example/videos?platforms=tiktok%2Cyoutube&start_date=2026-01-01&end_date=2026-01-31&order_by=rank&sort=desc&limit=25&offset=0&as_of=run",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()