# List change reports

> 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/trackers/{id}/changes`

This Tracker's Change Reports, newest first, readable after the Tracker is deleted. Quiet cycles are absent by design: no report means nothing tripped.

Each item is `{ id, tracker_id, run_id, cycle_key, triggers, changes, summary, created_at }`. `changes` has one key per tripped trigger, with before/after numbers.

Creator changes

- `followers`: `{ before, after, change, change_pct }`
- `new_videos`: `{ since, count, videos }`
- `outliers` and `velocity`: lists whose entries carry `before` (null for a video new to the Tracker) and `after`. History is at `GET /v1/videos/{platform}/{id}/snapshots`.
- `became_ad`: entries `{ id, url, before, after }`, each side the Video's `{ is_ad, paid_partnership }`. `before` is null when not reported.
- `bio_link_changed`: `{ before, after }` link lists.
- `verified_changed`: `{ before, after }` booleans.
- Firing: `became_ad`, `bio_link_changed` and `verified_changed` fire once, on the transition, only when the Platform reported the value on both sides. `became_ad` also counts an unreported `before`.

Advertiser changes

- `new_ads`: `{ since, count, ads }`. Each Ad adds `analysis` and `analysis_status`, read live, so a later read shows analysis finished after the cycle.
- `analysis`: `{ summary, hook_type, angle, offer_type, format }` as on stored Ads, or null.
- `analysis_status`: `ready`; `pending`, analysis may still land, up to 24 hours after the report on a Tracker with `intelligence` on; `none`, no analysis to expect, as with `intelligence` off.
- `stopped_ads`: `{ count, ads }`. An Ad gone from Meta's library counts, with `removed_from_library: true`.
- `variant_growth`: entries `{ before, after, added }`
- `new_countries_or_placements`: entries `{ countries, placements }`, only what is new.
- `crossed_30_days`: `{ count, ads }`, each `{ started_at, days_running }`: Ads still running that reached 30 days since the previous cycle. A signal, not proof that an Ad works: lifespan is a proxy for performance.
- `refresh_burst`: `{ new_ads, trailing_daily_median }`. New Ads this cycle reached at least 5 and at least 3 times the Advertiser's 28-day median of Ads started per day. Not raised when the previous cycle is over 48 hours old.
- Baseline: a first cycle raises neither `crossed_30_days` nor `refresh_burst`.
- `truncated: true`: the cycle hit its page cap with Ads unread.
- `incomplete: true`: the library failed part-way. The Run's result says so too.
- Ad entries: every one carries `id`, `library_id` and its Ad Library `url`.
- TikTok `new_ads`: entries add `targeting` `{ countries, ages, genders }`, `landing_page` and `cta` (null when not read).
- TikTok `reach_growth`: `{ count, ads }`, each `{ before, after }` audience buckets.

Hashtag and Keyword changes

- `median_views`: `{ before, after, change, change_pct, sample_based: true }`
- `new_top_videos`: `{ since, count, videos }`, each `{ id, url, views }`
- Coverage: a Keyword Tracker on Instagram or Facebook marks each report `coverage: "partial"`.

Sound changes

- `video_count`: `{ before, after, change, change_pct }`, rises only.
- `new_top_video`: `{ since, before, after }`, each side `{ id, url, views }`

With a Focus

- Filtered lists: `changes` lists only in-focus and unjudged Videos and `off_focus_count` counts the rest. Stats stay full-Sample.
- Seeing the rest: `include_off_focus=true` adds them as `off_focus_videos`, each with `focus: { verdict, reason }`.
- Off-focus-only cycles: a cycle whose only news is off focus writes no report and sends no webhook. Its Run's result records `off_focus_unreported`, and those Videos count in the next report's `off_focus_count`.

## Price

Free.

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | `string` | Required | — | Tracker id. |
| `since` | query | `string` format `date-time` | Optional | — | Only reports written after this ISO 8601 instant. |
| `limit` | query | `integer` min 1; max 100 | Optional | `25` | Items per page. |
| `cursor` | query | `string` | Optional | — | Opaque `next_cursor` from the previous page. |
| `include_off_focus` | query | `boolean` | Optional | — | `true`: each report with a Focus also lists the off-focus Videos it hid, as `off_focus_videos`, each with `focus: { verdict, reason }`. Default: not listed. |

## 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 Change Reports, newest first.
  - `id` string required
  - `tracker_id` string required
  - `run_id` string required nullable
  - `cycle_key` string required One report per Tracker per cycle.
  - `triggers` array of string required Creator: `new_videos`, `followers`, `outlier`, `velocity`, `became_ad`, `bio_link_changed`, `verified_changed`. Hashtag and Keyword: `median_views`, `new_top_videos`. Sound: `video_count`, `new_top_video`. Advertiser: `new_ads`, `stopped_ads`, `variant_growth`, `new_countries_or_placements`, `reach_growth` (TikTok only), `crossed_30_days`, `refresh_burst`.
  - `changes` any The before/after numbers behind the triggers.
  - `summary` string required nullable
  - `created_at` string required
  - `coverage` string always `partial` A Keyword Tracker's on Instagram or Facebook: their search is a best-effort index, so the numbers are too. Absent otherwise.
  - `off_focus_count` integer A Tracker with a Focus only: how many off-focus Videos `changes` left out, including those hidden by quiet cycles since the previous report. `changes` lists in-focus and unjudged Videos; stats stay full-Sample. Absent without a Focus.
  - `off_focus_videos` array of object Only with `include_off_focus=true`, on a report with a Focus: the Videos `off_focus_count` counts, each with `focus: { verdict, reason }`.
    - `id` string required
    - `url` string required nullable
    - `focus` object required
      - `verdict` string required one of `in_focus`, `off_focus`, `unjudged` `unjudged`: the Video could not be judged (or is not judged yet) and is shown.
      - `reason` string required

### 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).

## Related guides

- [Pagination](https://www.shortsintel.com/docs/concepts/pagination): Following `next_cursor` through a list.
- [Trackers](https://www.shortsintel.com/docs/concepts/trackers): Standing watches on a creator or an Advertiser: how a cycle runs, when it reports a change, and how to pause one.

## Request samples

curl:

```bash
curl "https://www.shortsintel.com/v1/trackers/trk_4b1e90c7aa/changes?limit=25" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

TypeScript:

```typescript
const response = await fetch(
  "https://www.shortsintel.com/v1/trackers/trk_4b1e90c7aa/changes?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/trackers/trk_4b1e90c7aa/changes?limit=25",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()
```

200 · `{ items, next_cursor }`.

```json
{
  "items": [
    {
      "id": "chg_2ac910f4d8",
      "tracker_id": "trk_4b1e90c7aa",
      "run_id": "run_c07a41bb92",
      "cycle_key": "tiktok:creator:someone:2026-09-08",
      "triggers": [
        "new_videos",
        "outlier"
      ],
      "changes": {
        "new_videos": {
          "before": 61,
          "after": 62,
          "count": 1,
          "videos": [
            {
              "id": "7300000000000000000",
              "url": "https://www.tiktok.com/@someone/video/7300000000000000000",
              "posted_at": "2026-09-05T06:32:11.000Z",
              "views": 1284000
            }
          ]
        },
        "outliers": [
          {
            "id": "7300000000000000000",
            "url": "https://www.tiktok.com/@someone/video/7300000000000000000",
            "views": 1284000,
            "outlier": 4.21,
            "threshold": 3
          }
        ]
      },
      "summary": "1 new video, 1 outlier at 4.2x median",
      "created_at": "2026-09-08T04:00:11.402Z"
    }
  ],
  "next_cursor": null
}
```

[Previous List stored Ads](https://www.shortsintel.com/docs/reference/trackers/list-tracker-ads)
