Skip to content
ShortsIntel
Create a key

API referenceTrackers

Set or clear a tracker's focus

PUT/v1/trackers/{id}/focus

Sets the Tracker's Focus and judges its latest Sample against it now, as a Run, so sample (a Creator: recent_videos, its newest Videos) already shows the new verdicts. Each edit is a new version: older Change Reports keep the verdicts they were built on, and going back to an earlier Focus reuses its verdicts. null clears the Focus: reads show every Video again. A kind that cannot take a Focus is 422 focus_unsupported_kind, which lists the kinds that can.

Price

+3 credits per Video the model judges, +1 credit per Video must_mention rules out; nothing for a Video already judged under this Focus (a preview included) or one that could not be judged. Clearing is free.

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, videos, to_judge }: every Video of the latest Sample not yet judged under this Focus at the model price. Nothing is judged or saved.

Request body

application/json

object

  • focusobjectrequirednullableThe new Focus, or null to clear it (free).
    • textstringrequiredWhich Videos are relevant to you, in plain language, exclusions included, e.g. Apple Inc. and its products (iPhone, Mac, AirPods, iOS). Not the fruit, recipes or orchards. 1 to 1000 characters.
    • must_mentionarray of stringUp to 20 terms of at most 60 characters. A Video that has captions or an analysis transcript, and whose caption, hashtags, captions and transcript name none of them (any case, whole term), is off focus without a model call; one with neither goes to the model, so a term said aloud still counts; one naming any is still judged against text.

Responses

200 OK

{ run, tracker, sample }; run is null and sample absent when the Focus was cleared. A replayed Idempotency-Key returns the original Run and is not charged again. With estimate=true, the quote instead.

any of 2 shapes

  • Option 1object
    • trackerobjectrequired
      • idstringrequired
      • kindstringrequiredone of creator, hashtag, sound, advertiser, keyword, videovideo is deprecated (ADR 0024): existing Video Trackers keep working, new ones are refused with 400 kind_deprecated.
      • platformstringrequiredmeta or tiktok 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
      • coveragestringone of library_regions_only, partialGET /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. Keyword on Instagram or Facebook: partial, their search being a best-effort index. Absent otherwise.
      • coverage_notestringThe regions the TikTok ad library covers, beside coverage.
      • focusobjectThe Tracker's Focus: which Videos are relevant to you. Terms are stored lowercased. Absent when it has none.
        • textstringrequired
        • must_mentionarray of stringrequired
    • sampleobjectOnly on a Tracker with a Focus: its latest Sample through the Focus.
      • atstringrequiredWhen the latest Sample's Snapshot was taken.
      • statsobjectrequiredThe full Sample's stats, unchanged by the Focus.
        • sampled_videosintegerrequired
        • views_totalnumberrequired
        • views_mediannumberrequirednullable
        • views_maxnumberrequirednullable
        • likes_totalnumberrequired
        • comments_totalnumberrequired
        • engagement_ratenumberrequirednullable
      • videosarray of objectrequiredIn-focus and unjudged Videos; with include_off_focus=true (and on a preview) every Video, each with focus.
        • platformstringrequired
        • idstringrequired
        • urlstringrequirednullable
        • descriptionstringrequired
        • posted_atstringrequirednullable
        • duration_secondsnumberrequirednullable
        • thumbnail_urlstringrequirednullable
        • hashtagsarray of stringrequired
        • soundobjectrequirednullable
          • idstringrequired
          • titlestringrequirednullable
        • creatorobjectrequirednullable
          • idstringrequired
          • handlestringrequirednullable
          • namestringrequired
          • follower_countnumberrequirednullable
        • snapshotobjectrequirednullable
          • atstringrequired
          • viewsnumberrequired
          • likesnumberrequired
          • commentsnumberrequired
          • sharesnumberrequired
          • savesnumberrequired
        • scoresobjectrequirednullableNull when the creator has no baseline yet.
          • outliernumberrequirednullableViews over the creator's median views.
          • outlier_p90numberrequirednullable
          • percentilenumberrequirednullableWhere this video sits in the creator's own sample, 0-100.
          • velocityobjectrequirednullable
            • views_per_hournumberrequired
            • windowstringrequired
          • reasonstringrequirednullablealways aged_outaged_out when the video is over 30 days old and Scores are null.
          • baselineobjectrequiredThe yardstick every Score on this creator is measured against.
            • median_viewsnumberrequired
            • p90_viewsnumberrequired
            • engagement_ratenumberrequirednullable
            • posts_per_weeknumberrequirednullable
            • sampleintegerrequired
            • confidencestringrequiredone of high, low
            • sourcestringrequiredone of videos, follower_tier
            • computed_atstringrequirednullable
            • stalebooleanrequiredTrue past 7 days; the next lookup refreshes it.
        • coveragestringalways partialPresent only where the platform's index is best-effort.
        • focusobject
          • verdictstringrequiredone of in_focus, off_focus, unjudgedunjudged: the Video could not be judged (or is not judged yet) and is shown.
          • reasonstringrequired
      • off_focus_countintegerrequiredVideos hidden as off focus.
      • focusobjectrequired
        • totalintegerrequiredVideos read.
        • in_focusintegerrequired
        • unjudgedintegerrequiredShown, but not counted in focus.
        • summarystringrequired"N of M in focus".
        • statsobjectrequiredStats over the in-focus Videos only.
          • sampled_videosintegerrequired
          • views_totalnumberrequired
          • views_mediannumberrequirednullable
          • views_maxnumberrequirednullable
          • likes_totalnumberrequired
          • comments_totalnumberrequired
          • engagement_ratenumberrequirednullable
    • recent_videosobjectOnly on a Creator Tracker with a Focus: its newest Videos through the Focus.
      • videosarray of objectrequiredThe Creator's newest Videos, newest first: in-focus and unjudged ones; with include_off_focus=true every Video, each with focus.
        • platformstringrequired
        • idstringrequired
        • urlstringrequirednullable
        • descriptionstringrequired
        • posted_atstringrequirednullable
        • duration_secondsnumberrequirednullable
        • thumbnail_urlstringrequirednullable
        • hashtagsarray of stringrequired
        • soundobjectrequirednullable
          • idstringrequired
          • titlestringrequirednullable
        • creatorobjectrequirednullable
          • idstringrequired
          • handlestringrequirednullable
          • namestringrequired
          • follower_countnumberrequirednullable
        • snapshotobjectrequirednullable
          • atstringrequired
          • viewsnumberrequired
          • likesnumberrequired
          • commentsnumberrequired
          • sharesnumberrequired
          • savesnumberrequired
        • scoresobjectrequirednullableNull when the creator has no baseline yet.
          • outliernumberrequirednullableViews over the creator's median views.
          • outlier_p90numberrequirednullable
          • percentilenumberrequirednullableWhere this video sits in the creator's own sample, 0-100.
          • velocityobjectrequirednullable
            • views_per_hournumberrequired
            • windowstringrequired
          • reasonstringrequirednullablealways aged_outaged_out when the video is over 30 days old and Scores are null.
          • baselineobjectrequiredThe yardstick every Score on this creator is measured against.
            • median_viewsnumberrequired
            • p90_viewsnumberrequired
            • engagement_ratenumberrequirednullable
            • posts_per_weeknumberrequirednullable
            • sampleintegerrequired
            • confidencestringrequiredone of high, low
            • sourcestringrequiredone of videos, follower_tier
            • computed_atstringrequirednullable
            • stalebooleanrequiredTrue past 7 days; the next lookup refreshes it.
        • coveragestringalways partialPresent only where the platform's index is best-effort.
        • focusobject
          • verdictstringrequiredone of in_focus, off_focus, unjudgedunjudged: the Video could not be judged (or is not judged yet) and is shown.
          • reasonstringrequired
      • off_focus_countintegerrequiredVideos hidden as off focus.
      • focusobjectrequired
        • totalintegerrequiredVideos read.
        • in_focusintegerrequired
        • unjudgedintegerrequiredShown, but not counted in focus.
        • summarystringrequired"N of M in focus".
        • statsobjectrequiredStats over the in-focus Videos only.
          • sampled_videosintegerrequired
          • views_totalnumberrequired
          • views_mediannumberrequirednullable
          • views_maxnumberrequirednullable
          • likes_totalnumberrequired
          • comments_totalnumberrequired
          • engagement_ratenumberrequirednullable
    • runobjectrequirednullableThe Run judging the latest Sample under the new Focus, charged per judgment. Null when the Focus was cleared.
      • 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, sample }`; `run` is null and `sample` absent when the Focus was cleared. A replayed Idempotency-Key returns the original Run and is not charged again. With `estimate=true`, the quote instead.

{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "focus_judgment",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 6,
    "list_price_credits": 6,
    "cached": false
  },
  "tracker": {
    "id": "trk_4b1e90c7aa",
    "kind": "keyword",
    "platform": "tiktok",
    "target": "ai video tools",
    "intelligence": false,
    "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",
    "focus": {
      "text": "Hands-on tips for AI video tools. Not product comparisons.",
      "must_mention": []
    }
  }
}

200 · With `estimate=true`: the quote, nothing judged or saved.

{
  "estimate_credits": 6,
  "cached": false,
  "videos": 2,
  "to_judge": 2
}

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, focus_unsupported_kind, 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 — the Balance cannot cover the quote. Nothing is judged or saved.

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, focus_unsupported_kind, 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 is 0 Credits and this operation needs 6 Credits. Nothing was charged.",
  "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, focus_unsupported_kind, 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."
}

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, focus_unsupported_kind, 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

focus_unsupported_kind — this kind of Tracker cannot take a Focus.

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, focus_unsupported_kind, 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/focus_unsupported_kind",
  "title": "Focus not supported for this kind",
  "status": 422,
  "code": "focus_unsupported_kind",
  "detail": "A Focus cannot be set on a advertiser Tracker.",
  "supported_kinds": [
    "keyword"
  ]
}

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, focus_unsupported_kind, 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

Use ShortsIntel to set or clear a tracker's focus.

- id: trk_4b1e90c7aa

Tell me what it will cost before you run it, then summarise what you find.

If you don't have ShortsIntel tools, don't guess: tell me to connect it first. Add the MCP server https://www.shortsintel.com/api/mcp (or install the ShortsIntel plugin), sign in, and retry. Setup guide: https://www.shortsintel.com/docs/mcp
  • 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 or TikTok Advertiser: how a cycle runs, when it reports a change, and how to pause one.