# Run a tracker cycle now

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

POST `/v1/trackers/{id}/refresh`

Runs the Tracker's cycle now, forcing a fresh fetch rather than reading a fresh Snapshot. `change_report` is null on a quiet cycle.

- Advertiser analysis: an Advertiser Tracker's new Ads are analysed in the background on `intelligence_run`, never in the request.
- Focus line: with a Focus, the Run's `result.focus` is `{ judged, gated, cached, unjudged, credits }`.
- Skipped Videos: a Creator's `off_focus_new_videos` counts the new Videos skipped as off focus.
- Hidden Videos: `off_focus_unreported` counts the off-focus Videos a cycle with no Change Report hid, carried into the next report's `off_focus_count`.

## Price

6 credits for a creator, 30 credits for an advertiser, plus 20 credits per new video when the Tracker opted into analysis (per new Ad, on its own Run, for an advertiser); a TikTok advertiser's new Ads' detail reads beyond 10 at 3 credits each, quoted at worst (every running Ad new, at most 300). Same price as a scheduled cycle.

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 |
| --- | --- | --- | --- | --- | --- |
| `id` | path | `string` | Required | — | Tracker id. |
| `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`. |
| `estimate` | query | `boolean` | Optional | — | Return `{ estimate_credits, cached, per_cycle }`, the cycle's floor price, and run nothing. With analysis on, each new video the cycle finds adds to the charge. |
| `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`. |

## Responses

### 200 OK

`{ run, tracker, change_report, intelligence_run }`. A replayed Idempotency-Key returns the original Runs and is not charged again. With `estimate=true`, `{ estimate_credits, cached, per_cycle }` 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
  - `tracker` object required
    - `id` string required
    - `kind` string required one of `creator`, `hashtag`, `sound`, `advertiser`, `keyword`, `video` `video` is deprecated (ADR 0024): existing Video Trackers keep working, new ones are refused with 400 `kind_deprecated`.
    - `platform` string required `meta` or `tiktok` for an advertiser Tracker.
    - `target` string required
    - `intelligence` boolean required Whether each new video (or Ad) the cycle finds is analysed.
    - `state` string required one of `active`, `paused`, `deleted`
    - `last_cycle_at` string required nullable
    - `last_run_id` string required nullable
    - `created_at` string required
    - `updated_at` string required
    - `coverage` string one of `library_regions_only`, `partial` `GET /v1/trackers/{id}`. TikTok advertiser: `library_regions_only` when its latest observation found no Ads in the TikTok ad library, which holds only Ads delivered in the EU/EEA, Switzerland, the UK and Turkey. Google advertiser: `partial` when it runs more Ads than a cycle lists. Keyword on Instagram or Facebook: `partial`, their search being a best-effort index. Absent otherwise.
    - `coverage_note` string The regions the TikTok ad library covers, beside `coverage`.
    - `focus` object The Tracker's Focus: which Videos are relevant to you. Terms are stored lowercased. Absent when it has none.
      - `text` string required
      - `must_mention` array of string required
  - `change_report` object required nullable Null on a quiet cycle.
    - `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
  - `intelligence_run` object required nullable Advertiser Trackers with `intelligence: true`: the Run analysing this cycle's new Ads in the background, charged per Ad computed. Null when no Ad needed analysis.
    - `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
- 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.

### 400 Bad Request

`invalid_request` — a malformed body. Or `unsupported_platform`: an unknown platform, or a creator on YouTube (creator Trackers cycle on TikTok, Instagram and Facebook). Nothing is created or 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

Code: `insufficient_balance`. 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

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

### 422 Unprocessable Content

`unsupported_kind` — a Video Tracker, which has no cycle. Only creator, hashtag, sound, advertiser and keyword Trackers cycle; nothing is run or charged.

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

### 429 Too Many Requests

`rate_limit_exceeded`, with `Retry-After`.

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

## Related guides

- [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.
- [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 -X POST "https://www.shortsintel.com/v1/trackers/trk_4b1e90c7aa/refresh" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

TypeScript:

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

data = response.json()
```

200 · `{ run, tracker, change_report, intelligence_run }`. A replayed Idempotency-Key returns the original Runs and is not charged again. With `estimate=true`, `{ estimate_credits, cached, per_cycle }` instead.

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "tracker_cycle",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 50,
    "list_price_credits": 50,
    "cached": false
  },
  "tracker": {
    "id": "trk_4b1e90c7aa",
    "kind": "creator",
    "platform": "tiktok",
    "target": "someone",
    "intelligence": true,
    "state": "active",
    "last_cycle_at": "2026-09-08T04:00:11.402Z",
    "last_run_id": "run_c07a41bb92",
    "created_at": "2026-09-01T11:20:03.118Z",
    "updated_at": "2026-09-08T04:00:11.402Z"
  },
  "change_report": {
    "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"
  },
  "intelligence_run": null
}
```

200 · With `estimate=true`: the cycle's floor price, nothing run or charged.

```json
{
  "estimate_credits": 6,
  "cached": false,
  "per_cycle": true
}
```

[Previous Stop tracking](https://www.shortsintel.com/docs/reference/trackers/delete-tracker)[Next Set or clear a tracker's focus](https://www.shortsintel.com/docs/reference/trackers/set-tracker-focus)
