# Look up a video by id

> 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/videos/{platform}/{id}`

Metadata, stats, the latest Snapshot and Scores for one video on TikTok, Instagram, YouTube or Facebook.

Ids by platform

- Instagram: the post's shortcode (`/p/{id}`, `/reel/{id}`) or the numeric media id search returns. Reels, photos and carousels are all videos. Instagram reports no shares or saves, so they are null.
- YouTube: the 11-character video id. `description` holds the title then the description, with no `sound` and null `shares`/`saves`, as YouTube publishes neither.
- Facebook: the numeric video or reel id. `shares` over 1,000 may be rounded as Facebook shows it (1.4K reads 1400).

Scores and history

- Scores: returned where the creator has a baseline, else `null` Scores rather than a fetch. `POST /videos/{platform}/{id}/score` forces it (TikTok only; other platforms are 400 `unsupported_platform` before any Run).
- History: the Snapshots behind `velocity` are at `GET /v1/videos/{platform}/{id}/snapshots`.

Adding analysis or a download

- One Run: any `include` makes the call one video analysis Run (kind `video_intelligence`) at a single price in place of the lookup price. `include` works on every platform, YouTube long-form included.
- Analysis and transcript prices: `include=intelligence` (alone or with `transcript`) is the analysis price. `include=transcript` alone is the flat transcript price.
- Download link: `include=download` adds `download_url`, a link to our own short-lived copy of the file. Anyone holding it can download the file. While downloads are switched off it is refused with 422 `feature_unavailable`, before any Run and uncharged.
- Link expiry: `download_expires_at`, 7 days after the copy was made and at least a day away. Ask again for a fresh link.
- Download price: alone it is the download price. With `intelligence` or `transcript` it is added to theirs, copy or no copy.
- Failed copy: with `download` beside `intelligence` or `transcript`, a file that cannot be copied does not fail the analysis. The result carries `download_error` and the download is not charged.

Errors

- Unavailable media: a post gone, private or restricted fails the Run with `media_unavailable`, uncharged.
- Long videos: a video over 10 minutes is refused for analysis and download with 422 `video_too_long`, before any Run when its length is known (YouTube is asked first, free), else the Run fails uncharged.

[Open in Playground](https://www.shortsintel.com/console/playground?op=getVideo&platform=tiktok&id=7300000000000000000) (no API Key needed)

## Price

3 credits. With `include=intelligence`: 23 credits instead of the lookup price. With `include=transcript` only: a flat 10 credits. With `include=download`: 3 credits alone, else 3 credits on top of the analysis or transcript price. A stored answer (or an existing copy) costs the same as a fresh one.

Supports `estimate=true`: the reply is the price in Credits and whether it would be `cached`, with no Run created and nothing charged.

A cached result costs the same as a fresh one; `cached` says which you got.

## 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. |
| `include` | query | `string[]` one of `intelligence`, `transcript`, `download` | Optional | — | `intelligence` adds the full analysis object (a TikTok photo carousel is analysed from its images, slide by slide); `transcript` adds the speech (`source` `caption` or `whisper`); `download` adds `download_url` and `download_expires_at` (refused for a photo carousel: `media_unavailable`, reason `not_a_video`). Repeat the param or comma-separate (`include=intelligence,download`). Any value changes the price; see above. |
| `refresh` | query | `boolean` | Optional | — | Only with `include`. `true` recomputes the analysis even when a current one is stored, and is charged as fresh. Ignored without `include`. |
| `wait` | query | `integer` min 0; max 120 | Optional | `30` | Seconds to hold the response open before handing back a running Run to poll. Default 30, max 120. A POST may send it in the body instead; different values in both places are a 400. |
| `max_credits` | query | `integer` min 0 | Optional | — | Most Credits the call may cost. A higher quote is a 402 `max_credits_exceeded`, no Run. Where `x-price.max_credits` is null, the Run stops at it and settles `partial`. |
| `estimate` | query | `boolean` | Optional | — | `true` returns `{ estimate_credits, cached }` from what is already stored, creating no Run. Nothing is charged. If a source the call would read is unavailable and the cache cannot answer, the estimate adds `unavailable` (the `{ platform, capability }` parts it cannot reach), or is a 503 `source_unavailable` when it can reach none. Only `true` or `false`, else a 400. A POST may send it in the body instead; different values in both places are a 400. |
| `Idempotency-Key` | header | `string` | Optional | — | 1-255 printable ASCII characters. The same key and payload returns the original Run (202 while running); a different payload or operation is a 409 `idempotency_conflict`. |

## Responses

### 200 OK

The Run finished inside the wait budget: `{ run, result }`. With `estimate=true`, `{ estimate_credits, cached }` instead.

any of 2 shapes

- Option 1 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 the same inline or 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 A running Research's `stage` and counts so far, such as `analysed` of `shortlisted`; a count is absent until known. Absent once the Run settles and on other kinds.
      - `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 One normalised video, the same shape on every platform.
    - `platform` string required
    - `id` string required
    - `url` string required nullable
    - `description` string required nullable Null when the read fetched no caption.
    - `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, false for a catalogue track. Null when not reported.
    - `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, else the platform's URL, which may expire: download it rather than store the link.
      - `verified` boolean required nullable The verified badge, from the latest profile read, else this video's. Null when unreported.
    - `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). Null when none or not reported.
    - `commerce` object required nullable What the Platform declares, never inferred from the content. A flag is null when not reported, never false; the object is null when nothing was.
      - `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 Accounts the Video mentions or names (on Instagram, tagged users first). Null when 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.
    - `is_pinned` boolean required nullable Pinned to the top of the creator's feed (Instagram). Null when not reported.
    - `is_sponsored` boolean required nullable Ad flag, #ad or #…partner tag, or a brand collaborator. Null: unchecked.
    - `sponsor` string required nullable The sponsoring brand's handle when is_sponsored.
    - `snapshot` object required nullable Deprecated: use `engagement`.
      - `at` string required
      - `views` number required nullable
      - `likes` number required nullable
      - `comments` number required nullable
      - `shares` number required nullable
      - `saves` number required nullable
    - `engagement` object required nullable A count the platform did not report is null, never 0.
      - `views` number required nullable
      - `likes` number required nullable
      - `comments` number required nullable
      - `shares` number required nullable
      - `saves` number required nullable
      - `at` string 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
        - `since` string required nullable When the window starts.
      - `engagement_rate` number required nullable This video's reported interactions (likes, comments, shares, saves) over its views. Null when unknown.
      - `anomaly` boolean required nullable True when `engagement_rate` is under 20% of the baseline's, as paid or boosted views read. Null when unknown.
      - `reason` string required nullable always `aged_out` `aged_out` when the video is over 30 days old and the view 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.
    - `transcript` object With `include=transcript`: the speech, not the scene breakdown (changed 2026-11-09).
      - `version` integer required
      - `source` string required nullable one of `caption`, `whisper` `caption`: the Platform's caption track. `whisper`: speech-to-text on the audio.
      - `computed_at` string required
      - `transcript` string required nullable What is said, one line per line. Empty with no speech; null when it could not be read.
      - `language` string required nullable
      - `segments` array of object required nullable
        - `start_ms` integer required
        - `end_ms` integer required
        - `text` string required
    - `download_url` string With `include=download`: a link to the video file, served from our own copy. Works until `download_expires_at`; anyone holding it can download the file.
    - `download_expires_at` string With `include=download`: when `download_url` stops working, 7 days after our copy was made (at least a day away).
    - `download_error` object With `include=download` beside analysis: why the file could not be copied (e.g. `media_unavailable`, too large). The analysis is still served and the download is not charged. Its fields are on [Errors](https://www.shortsintel.com/docs/reference/errors).
- Option 2 object Returned instead of a Run when `estimate=true`. Nothing is charged; some operations add members.
  - `estimate_credits` integer required What the call would be charged, in Credits.
  - `cached` boolean required Whether a stored result can already answer. It does not change the price.

### 202 Accepted

Still running: `{ run }`. Poll `GET /v1/runs/{id}`.

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 the same inline or 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}`, the body's copy of the `Location` header (for MCP). Present only while `running`.

202 · Example

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "video_lookup",
    "status": "running",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": null,
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  },
  "poll_url": "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b"
}
```

### 400 Bad Request

`invalid_request` (a malformed id, `wait`, `estimate` or Idempotency-Key) or `unsupported_platform`, refused before any Run opens. Nothing is charged.

Codes: `invalid_request`, `unsupported_platform`. 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).

### 402 Payment Required

`insufficient_balance`: the Balance cannot cover the quoted price (the worst case for Research and enriched search). No Run opens and nothing is charged; a multi-item Run that runs short later charges its completed items up to the Balance and ends `partial`.

Code: `insufficient_balance`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 409 Conflict

`idempotency_conflict` — the same Idempotency-Key with a different payload.

Code: `idempotency_conflict`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 429 Too Many Requests

`rate_limit_exceeded` or `concurrency_limit_exceeded`, with `Retry-After`.

Codes: `rate_limit_exceeded`, `concurrency_limit_exceeded`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 502 Bad Gateway

A Run that opened and then failed answers `application/problem+json` with its problem's status (`vendor_error` here, `not_found` as 404) and the Run envelope, keeping the Run id. Never charged. The example is a Video lookup's.

Code: `vendor_error`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 503 Service Unavailable

`source_unavailable`: every source this Run reads failed or is switched off. The Run fails uncharged, envelope alongside; `endpoints` names the source. Retry after `retry_after_seconds` (also `Retry-After`); it does not mean empty. The example is a Video lookup's.

Code: `source_unavailable`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

## Related guides

This call creates a Run. With `wait` it holds the response open until the Run finishes or the wait runs out, then answers with the finished result or `202` and 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.
- [Pricing and estimates](https://www.shortsintel.com/docs/concepts/pricing-and-estimates): Credits, estimates and why a cached result costs the same as a fresh one.
- [Addressing videos and creators](https://www.shortsintel.com/docs/concepts/addressing): Naming a video, creator, hashtag or sound.
- [Analysis](https://www.shortsintel.com/docs/concepts/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](https://www.shortsintel.com/docs/concepts/scores): Outlier and velocity, how a creator baseline is built, what confidence means, and when a score stops being reported.

## Request samples

curl:

```bash
curl "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?wait=30" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

TypeScript:

```typescript
const response = await fetch(
  "https://www.shortsintel.com/v1/videos/tiktok/7300000000000000000?wait=30",
  {
    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/videos/tiktok/7300000000000000000?wait=30",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()
```

200 · The Run finished inside the wait budget: `{ run, result }`. With `estimate=true`, `{ estimate_credits, cached }` instead.

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "video_lookup",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 3,
    "list_price_credits": 3,
    "cached": false
  },
  "result": {
    "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,
    "is_pinned": null,
    "is_sponsored": null,
    "sponsor": null,
    "snapshot": {
      "at": "2026-09-08T09:14:04.219Z",
      "views": 1284000,
      "likes": 143200,
      "comments": 2810,
      "shares": 9040,
      "saves": 21600
    },
    "engagement": {
      "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",
        "since": "2026-10-03T08:00:00.000Z"
      },
      "engagement_rate": 0.1376,
      "anomaly": false,
      "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
      }
    }
  }
}
```

200 · With `estimate=true`: the price, no Run, no charge.

```json
{
  "estimate_credits": 3,
  "cached": false
}
```

[Previous Look up many videos by URL](https://www.shortsintel.com/docs/reference/videos/lookup-videos)[Next Analyse a video](https://www.shortsintel.com/docs/reference/videos/compute-video-intelligence)
