# Read a video's metric history

> 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}/snapshots`

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

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

## Price

Free.

## Parameters

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

## Responses

### 200 OK

`{ items, next_cursor }`.

object

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

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

200 · `{ items, next_cursor }`.

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

### 400 Bad Request

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

Code: `invalid_request`. The problem body and every code are on [Errors](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

`not_found` — including anything belonging to another Customer.

Code: `not_found`. 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/videos/tiktok/7300000000000000000/snapshots?limit=25" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

TypeScript:

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

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

const data = await response.json();
```

Python:

```python
import requests

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

data = response.json()
```

## Related guides

- [Pagination](https://www.shortsintel.com/docs/concepts/pagination): Following `next_cursor` through a list.
- [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.

[Previous Read a comment's replies](https://www.shortsintel.com/docs/reference/videos/get-comment-replies)