# Read a breakdown's status > 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}` A Breakdown's status, answered as `GET /v1/research/{id}` answers it. An intent-mode Research id is the same 404 as an unknown id. [Open in Playground](https://www.shortsintel.com/console/playground?op=getBreakdown&id=id_example) (no API Key needed) ## Price Free, forever. Collection is the only thing charged. ## Parameters | Name | In | Type | Required | Default | Description | | --- | --- | --- | --- | --- | --- | | `id` | path | `string` | Required | — | Breakdown id — the id of its Run. | ## Responses ### 200 OK `{ run, result }` once the research has settled. object The envelope every charged operation answers with: `{ run }` while the Run is running (plus `poll_url` on the 202), joined by `result` once it completes or `error` once it fails. - `run` object required Every charged operation creates a Run. The envelope is identical whether the result came back inline or was polled. - `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 - `result` object required What a research recorded about itself: the intent, the keywords derived from it, coverage per platform, the counts, and the digest. The videos, creators, hashtags and sounds behind it page separately. - `digest_version` integer required - `mode` string one of `keywords`, `creators` What the research was seeded with: `keywords` (an intent) or `creators` (a breakdown). Absent means `keywords`. - `intent` string - `keywords` array of string - `keyword_rationale` string - `coverage` map of string required - `digest` object required - `summary` string required Two or three sentences answering the intent directly: what is working on this topic right now, across the videos analysed. - `themes` array of object required items 1 to 8 - `name` string required Short label, three or four words. - `share` number required value 0 to 1 Fraction of the analysed videos that belong to this theme, 0-1. - `description` string required What the videos in this theme have in common. - `video_ids` array of string required `video_id` keys (platform:id) of the analysed videos that belong to this theme, exactly as given in the evidence. - `hooks` array of object required items at most 12 - `text` string required The opening line, quoted VERBATIM from the evidence. Never paraphrase, never invent. - `video_id` string required `video_id` key (platform:id) of the video this hook is quoted from, exactly as given in the evidence. - `hook_type` string required The kind of hook, e.g. question, claim, negation, stat. - `why_it_works` string required One sentence. - `template` string length at least 1 The verbatim hook with its specifics (product, number, mistake, outcome, audience) replaced by short bracketed slots, every other word kept as spoken, e.g. "Stop [mistake] if you want [outcome]". - `lift` object nullable The `lift_tables.hook_type` row for the quoted video's analysed hook type, attached in code (never written by the model). Null when that video has no analysed hook type. - `value` string required The analysed hook type, or format + hook type, the row is keyed by. - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable - `views_lift` number required nullable - `engagement_lift` number required nullable - `low_confidence` boolean required - `sentiment` object required - `positive` number required value 0 to 1 - `neutral` number required value 0 to 1 - `negative` number required value 0 to 1 - `note` string required One sentence on what drives the distribution. - `angles` array of object required items 1 to 8 - `angle` string required A content angle worth trying. - `rationale` string required Why the evidence supports it, referencing what was seen. - `formulas` array of object items at most 5 - `name` string required Short label, three to five words. - `recipe` string required One line saying how to make it: the format, how it opens, and the order of its beats. - `visual_format` string required The visual format, copied exactly as it appears in `lift_tables.visual_format`. - `hook_type` string required The hook type, copied exactly as it appears in `lift_tables.hook_type`. - `structure` string required The beat structure the example videos share, as short beats joined by arrows, e.g. "problem → demo → result → CTA". - `video_ids` array of string required Up to 3 `video_id` keys (platform:id) of analysed videos that follow this formula, best performing first, exactly as given in the evidence. - `lift` object required nullable The `lift_tables.format_hook` row for this formula's visual format and hook type, attached in code (never written by the model): its `video_count` and lifts. The lift is for the format + hook type pair only; the structure is not bucketed. Null when no analysed video has that pair. - `value` string required The analysed hook type, or format + hook type, the row is keyed by. - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable - `views_lift` number required nullable - `engagement_lift` number required nullable - `low_confidence` boolean required - `gaps` array of object items at most 5 Up to 5 things the audience asks for in the top 10 videos' comments that no analysed video addresses, each with verbatim quoted comments (and the video they came from) and a suggested angle. Empty when no comments were available. Absent on research recorded before gaps existed. - `ask` string required What the audience asks for or complains about, in one sentence, in your own words. - `comments` array of object required items 1 to 3 - `text` string required A comment quoted VERBATIM from , character for character. Never paraphrase, never invent. - `video_id` string required `video_id` key (platform:id) of the video this comment was left under, exactly as given in . - `angle` string required A video someone could make that answers this ask, in one sentence. - `lift_tables` object Lift tables computed in code over the analysed videos: per visual format, hook type and length bucket, the video count, median views and engagement rate, and lift versus the whole set's median. The Digest quotes lifts only from these. Absent on research recorded before they existed. - `basis` string one of `set_median`, `creator_median` - `set` object required - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable - `visual_format` array of object required - `value` string required The visual format, hook type, length bucket, or ` + `. - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable (likes + comments + shares + saves) / views. - `views_lift` number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown. - `engagement_lift` number required nullable - `low_confidence` boolean required True when the row rests on fewer than 3 videos. - `hook_type` array of object required - `value` string required The visual format, hook type, length bucket, or ` + `. - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable (likes + comments + shares + saves) / views. - `views_lift` number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown. - `engagement_lift` number required nullable - `low_confidence` boolean required True when the row rests on fewer than 3 videos. - `length` array of object required - `value` string required The visual format, hook type, length bucket, or ` + `. - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable (likes + comments + shares + saves) / views. - `views_lift` number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown. - `engagement_lift` number required nullable - `low_confidence` boolean required True when the row rests on fewer than 3 videos. - `format_hook` array of object Visual format and hook type together, `value` as ` + `: the rows the Digest's formulas take their lift from. Absent on research recorded before it existed. - `value` string required The visual format, hook type, length bucket, or ` + `. - `video_count` integer required - `median_views` number required nullable - `median_engagement_rate` number required nullable (likes + comments + shares + saves) / views. - `views_lift` number required nullable Median views of this row over the whole set's median views. Null when the set median is 0 or unknown. - `engagement_lift` number required nullable - `low_confidence` boolean required True when the row rests on fewer than 3 videos. - `breakdown` object Breakdown only: the Creators read and how many Videos each returned, and those that could not be read. - `videos_per_creator` integer required Recent Videos asked for per Creator. - `creators` array of object required Every Creator read, in request order, each charged its fee. - `platform` string required - `handle` string required - `id` string required - `videos_read` integer required Videos read; fewer than `videos_per_creator` when `ended`. - `ended` boolean required True when the Creator's feed ran out before `videos_per_creator`. - `failed` array of object Creators that could not be read, charged 0, each with its problem `code` and `detail`. The Run is then partial. - `platform` string required - `handle` string required - `code` string required - `detail` string required - `lift_videos` integer Analysed Videos with a view count, of `analysed_videos`: the ranking and lift basis. The rest are unscored. - `analysed_videos` integer Videos analysed, of all the Creators read. - `research` object required - `requested` integer required - `completed` integer required - `failed` integer required - `cached` integer required - `fresh` integer required - `max_videos` integer required - `included_videos` integer required - `shortlisted` map of integer Shortlist places per requested platform: a guaranteed part each, then the rest by how many on-topic candidates each had. - `dropped_off_topic` integer Candidates judged off-topic and dropped before the shortlist; never charged. - `dropped_unsure` integer Candidates whose relevance was unsure and that ranked too low to keep; never charged. - `dropped_sample` array of object Up to 10 dropped candidates, best-ranked first, with why each was dropped. Absent on research recorded before it existed. - `video_id` string required `platform:id` of the dropped video. - `verdict` string required one of `off_topic`, `unsure` - `reason` string required The relevance check's reason, short. 200 · `{ run, result }` once the research has settled. ```json { "run": { "id": "run_c07a41bb92", "kind": "research", "status": "partial", "created_at": "2026-09-08T09:14:02.418Z", "completed_at": "2026-09-08T09:14:04.930Z", "charge_credits": 500, "list_price_credits": 500, "cached": false }, "result": { "digest_version": 2, "mode": "keywords", "intent": "why are cold plunge videos taking off", "keywords": [ "cold plunge", "ice bath", "cold exposure", "cold plunge routine" ], "keyword_rationale": "The intent is about a practice rather than a product, so the keywords cover the practice and its two common synonyms.", "coverage": { "tiktok": "complete", "instagram": "partial" }, "digest": { "summary": "Cold plunge videos are travelling on measured personal diaries rather than on science explainers. The videos that break out open on an unimpressive first number and pay it off with a later one, and keep the discomfort on camera instead of cutting around it. Sentiment is broadly positive, with the negative share concentrated on the cost of equipment.", "themes": [ { "name": "30-day diaries", "share": 0.45, "description": "One creator, one tub, a counter on screen, and the change stated as a number rather than a feeling.", "video_ids": [ "tiktok:7300000000000000000" ] }, { "name": "Before-workout plunging", "share": 0.2, "description": "Shorter clips arguing about timing relative to training, usually with a gym setting.", "video_ids": [ "tiktok:7300000000000000042" ] } ], "hooks": [ { "text": "Day one I lasted eleven seconds.", "video_id": "tiktok:7300000000000000000", "hook_type": "stat", "why_it_works": "An unimpressive concrete number sets up a payoff the viewer stays for.", "template": "Day one I lasted [small number] [unit].", "lift": { "value": "STORY", "video_count": 9, "median_views": 1840000, "median_engagement_rate": 0.0912, "views_lift": 1.6, "engagement_lift": 1.21, "low_confidence": false } } ], "sentiment": { "positive": 0.62, "neutral": 0.23, "negative": 0.15, "note": "Enthusiasm for the routine itself; the negative share is almost entirely the price of a tub." }, "angles": [ { "angle": "Open on the day-30 number and work backwards to day one.", "rationale": "Every diary in the shortlist that led with the outcome outperformed the ones that led with the method." } ], "gaps": [ { "ask": "Viewers want a cold plunge setup that does not cost hundreds.", "comments": [ { "text": "ok but what do I do if I can't afford a 600 dollar tub", "video_id": "tiktok:7300000000000000000" } ], "angle": "A 30-day diary on a chest freezer or bathtub build, with the receipt on screen." } ] }, "research": { "requested": 50, "completed": 48, "failed": 2, "cached": 11, "fresh": 37, "max_videos": 50, "included_videos": 50 } } } ``` ### 202 Accepted `{ run }` while the research is still collecting — the same body `GET /v1/runs/{id}` returns, not an error. `run.progress` says how far it has got. object Still running. Poll `poll_url` (`GET /v1/runs/{id}`), waiting the 202's `Retry-After` seconds between polls. - `run` object required Every charged operation creates a Run. The envelope is identical whether the result came back inline or was polled. Its fields are on [Poll or re-read a run](https://www.shortsintel.com/docs/reference/runs/get-run#response-200). - `poll_url` string required format `uri` Absolute URL of `GET /v1/runs/{id}` for this Run, the body's copy of the 202's `Location` header for callers that never see headers (MCP). Present only while the Run is `running`. 202 · Example ```json { "run": { "id": "run_c07a41bb92", "kind": "research", "status": "running", "created_at": "2026-09-08T09:14:02.418Z", "completed_at": null, "charge_credits": 0, "list_price_credits": 0, "cached": false, "progress": { "stage": "analysing", "keywords": 6, "searches": 12, "found": 214, "judged": 100, "kept": 81, "dropped_off_topic": 17, "dropped_unsure": 2, "shortlisted": 50, "analysed": 32, "updated_at": "2026-09-08T09:14:41.007Z" } }, "poll_url": "https://www.shortsintel.com/v1/runs/run_c07a41bb92" } ``` ### 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). ### 502 Bad Gateway A research whose Run failed is answered as `application/problem+json` with its problem's status, the problem members beside the unchanged Run envelope — exactly as `GET /v1/runs/{id}` answers it. Code: `vendor_error`. 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" \ -H "Authorization: Bearer sk_live_YOUR_KEY" ``` TypeScript: ```typescript const response = await fetch( "https://www.shortsintel.com/v1/breakdowns/id_example", { 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", headers={ "Authorization": "Bearer sk_live_YOUR_KEY", }, ) response.raise_for_status() data = response.json() ``` ## Related guides This call creates a Run. It can answer `202` with the running Run. Poll [`GET /v1/runs/{id}`](https://www.shortsintel.com/docs/reference/runs/get-run) until it settles; re-reading a Run is free. - [Runs](https://www.shortsintel.com/docs/concepts/runs): How a call becomes a Run, waiting inline, polling and free re-reads. [Previous Break down what works for a set of Creators](https://www.shortsintel.com/docs/reference/breakdowns/create-breakdown)[Next Filter a breakdown's videos](https://www.shortsintel.com/docs/reference/breakdowns/list-breakdown-videos)