Skip to content
ShortsIntel
Create a key

API referenceTrackers

Run a tracker cycle now

POST/v1/trackers/{id}/refresh

Runs the Tracker's cycle immediately, forcing the vendor call rather than reading a fresh Snapshot. change_report is null on a quiet cycle. An Advertiser Tracker's new Ads are analysed in the background on intelligence_run, never inside the request.

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

NameInTypeRequiredDefaultDescription
idpathstringRequired—Tracker id.
Idempotency-KeyheaderstringOptional—1-255 printable ASCII characters. Replaying this key with the same payload returns the original Run (202 while it is still running); a different payload, or a different operation, is a 409 idempotency_conflict.
estimatequerybooleanOptional—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.

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 1object
    • runobjectrequiredEvery charged operation creates a Run. The envelope is identical whether the result came back inline or was polled.
      • idstringrequired
      • kindstringrequiredWhat was run, e.g. video_lookup.
      • statusstringrequiredone of running, completed, partial, failedpartial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
      • created_atstringrequiredRFC 3339.
      • completed_atstringrequirednullableNull while the Run is still running.
      • charge_creditsintegerrequiredWhat this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
      • list_price_creditsintegerrequiredThe full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
      • cachedbooleanrequiredTrue when a stored result answered without paying the vendor.
      • progressobjectWhat a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
        • stagestringrequiredone of keywords, searching, filtering, analysing, writing_digest
        • keywordsintegervalue at least 0
        • searchesintegervalue at least 0
        • foundintegervalue at least 0
        • judgedintegervalue at least 0
        • keptintegervalue at least 0
        • dropped_off_topicintegervalue at least 0
        • dropped_unsureintegervalue at least 0
        • shortlistedintegervalue at least 0
        • analysedintegervalue at least 0
        • updated_atstringrequired
    • trackerobjectrequired
      • idstringrequired
      • kindstringrequiredone of creator, hashtag, sound, advertiser, videovideo is deprecated (ADR 0024): existing Video Trackers keep working, new ones are refused with 400 kind_deprecated.
      • platformstringrequiredmeta for an advertiser Tracker.
      • targetstringrequired
      • intelligencebooleanrequiredWhether each new video (or Ad) the cycle finds is analysed.
      • statestringrequiredone of active, paused, deleted
      • last_cycle_atstringrequirednullable
      • last_run_idstringrequirednullable
      • created_atstringrequired
      • updated_atstringrequired
    • change_reportobjectrequirednullableNull on a quiet cycle.
      • idstringrequired
      • tracker_idstringrequired
      • run_idstringrequirednullable
      • cycle_keystringrequiredOne report per Tracker per cycle.
      • triggersarray of stringrequiredCreator: new_videos, followers, outlier, velocity. Advertiser: new_ads, stopped_ads, variant_growth, new_countries_or_placements.
      • changesanyThe before/after numbers behind the triggers.
      • summarystringrequirednullable
      • created_atstringrequired
    • intelligence_runobjectrequirednullableAdvertiser 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.
      • idstringrequired
      • kindstringrequiredWhat was run, e.g. video_lookup.
      • statusstringrequiredone of running, completed, partial, failedpartial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
      • created_atstringrequiredRFC 3339.
      • completed_atstringrequirednullableNull while the Run is still running.
      • charge_creditsintegerrequiredWhat this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
      • list_price_creditsintegerrequiredThe full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
      • cachedbooleanrequiredTrue when a stored result answered without paying the vendor.
      • progressobjectWhat a running Research has done so far, refreshed as it works: stage (keywords, searching, filtering, analysing, writing_digest) and the counts known by then — keywords, found, kept, dropped_off_topic, and analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
        • stagestringrequiredone of keywords, searching, filtering, analysing, writing_digest
        • keywordsintegervalue at least 0
        • searchesintegervalue at least 0
        • foundintegervalue at least 0
        • judgedintegervalue at least 0
        • keptintegervalue at least 0
        • dropped_off_topicintegervalue at least 0
        • dropped_unsureintegervalue at least 0
        • shortlistedintegervalue at least 0
        • analysedintegervalue at least 0
        • updated_atstringrequired
  • Option 2objectReturned instead of a Run when estimate=true. Nothing is charged. Operations with more to say about a quote add members; the two above are always present.
    • estimate_creditsintegerrequiredWhat the call would be charged, in Credits.
    • cachedbooleanrequiredWhether a stored result can already answer. It does not change the price.

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.

{
  "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.

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

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.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

400 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/unsupported_platform",
  "title": "Unsupported platform",
  "status": 400,
  "code": "unsupported_platform",
  "detail": "Tracking a creator on youtube is not available yet. Creator Trackers are supported on: tiktok, instagram, facebook."
}

401 Unauthorized

missing_authorization, invalid_key, key_revoked or invalid_token.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

401 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/invalid_key",
  "title": "Invalid key",
  "status": 401,
  "code": "invalid_key",
  "detail": "That API key does not exist. Keys look like `sk_live_...` and are created in the console."
}

402 Payment Required

insufficient_balance.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

402 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "code": "insufficient_balance",
  "detail": "Your balance does not cover this operation. Top up in the console.",
  "balance_credits": 0,
  "required_credits": 6
}

404 Not Found

not_found.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No Tracker with that id for this Customer, or the creator no longer exists."
}

409 Conflict

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

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

409 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/idempotency_conflict",
  "title": "Idempotency conflict",
  "status": 409,
  "code": "idempotency_conflict",
  "detail": "This Idempotency-Key was used with a different payload.",
  "run_id": "run_8f2c1ad04b"
}

422 Unprocessable Content

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

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

422 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/unsupported_kind",
  "title": "Unsupported kind",
  "status": 422,
  "code": "unsupported_kind",
  "detail": "Tracking video targets is not available yet. Creator, hashtag, sound and advertiser tracking are supported today.",
  "supported_kinds": [
    "creator",
    "hashtag",
    "sound",
    "advertiser"
  ]
}

429 Too Many Requests

rate_limit_exceeded, with Retry-After.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose.

  • typestringrequired
  • titlestringrequired
  • statusintegerrequired
  • codestringrequiredone of missing_authorization, invalid_key, key_revoked, invalid_token, organization_not_selected, organization_access_revoked, connection_revoked, forbidden, invalid_request, unsupported_platform, unsupported_kind, kind_deprecated, not_found, video_too_long, idempotency_conflict, run_not_ready, advertiser_ambiguous, insufficient_balance, rate_limit_exceeded, concurrency_limit_exceeded, tracker_limit_exceeded, webhook_limit_exceeded, webhook_rotation_in_progress, collection_limit_exceeded, collection_name_taken, collection_kind_mismatch, media_unavailable, vendor_error, source_unavailable, service_unavailable, internal_errorStable machine-readable code.
  • detailstring

429 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/rate_limit_exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limit_exceeded",
  "detail": "60 requests per minute per key. Retry after the number of seconds in `Retry-After`.",
  "limit": 60
}

Request samples

curl -X POST "https://www.shortsintel.com/v1/trackers/trk_4b1e90c7aa/refresh" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
  • Pricing and estimates: Credits, estimates and why a cached result costs the same as a fresh one.
  • Trackers: Standing watches on a creator or a Meta Advertiser: how a cycle runs, when it reports a change, and how to pause one.