# Filter a breakdown's videos > For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md). 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](https://www.shortsintel.com/console/playground?op=listBreakdownVideos&id=id_example&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) (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 }`. ```json { "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](https://www.shortsintel.com/docs/reference/errors). ### 401 Unauthorized Codes: `missing_authorization`, `invalid_key`, `key_revoked`, `key_expired`, `invalid_token`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors). ### 404 Not Found Code: `not_found`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors). ### 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](https://www.shortsintel.com/docs/reference/errors). ## Request samples curl: ```bash 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" ``` TypeScript: ```typescript 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(); ``` Python: ```python 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() ``` [Previous Read a breakdown's status](https://www.shortsintel.com/docs/reference/breakdowns/get-breakdown)[Next Read a breakdown's creators and medians](https://www.shortsintel.com/docs/reference/breakdowns/list-breakdown-creators)