Preview a focus on a tracker
/v1/trackers/{id}/focus/previewJudges a proposed Focus on the Tracker's latest Sample without saving it: every Video with its verdict and reason, and how many would be hidden.
- Setting it later: its verdicts are kept under that Focus, so setting it afterwards with
PUT /v1/trackers/{id}/focuscosts nothing more. - Unsupported kinds: 422
focus_unsupported_kind, which lists the kinds that can.
Price
As setting the Focus: +3 credits per Video the model judges, +1 credit per Video must_mention rules out, nothing for a Video already judged under it.
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. 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. |
estimate | query | boolean | Optional | — | Return { estimate_credits, cached, videos, to_judge } and judge nothing. |
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. |
Request body
application/json
object
focusobject required The Focus to judge, not saved.textstring required Which 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 string Up 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 againsttext.
estimatebooleantruereturns{ estimate_credits, cached }, creates no Run and charges nothing.
Responses
200 OK
{ run, focus, sample }; sample is null when the Tracker has no Sample yet. With estimate=true, the quote instead.
any of 2 shapes
Option 1 object
runobject required The Run judging the latest Sample, charged per judgment.idstring requiredkindstring required What was run, e.g.video_lookup.statusstring required one ofrunning,completed,partial,failedpartialkeeps the completed items and charges for them, up to what the Balance covers;failedcharges nothing.created_atstring required RFC 3339.completed_atstring required nullable Null while the Run is still running.charge_creditsinteger required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.list_price_creditsinteger required The full price of the work asked for, in Credits. Equal tocharge_creditsunless the Run charged for only part of it.cachedboolean required True when a stored result answered without a fresh fetch.progressobject What a running Research has done so far, refreshed as it works: itsstageand the counts known by then, such asanalysedofshortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.stagestring required one ofkeywords,searching,reading_creators,filtering,analysing,writing_digestkeywordsinteger value at least 0creatorsinteger value at least 0creators_readinteger value at least 0searchesinteger value at least 0foundinteger value at least 0judgedinteger value at least 0keptinteger value at least 0dropped_off_topicinteger value at least 0dropped_unsureinteger value at least 0shortlistedinteger value at least 0analysedinteger value at least 0updated_atstring required
focusobject required The Focus previewed, as it would be stored.textstring requiredmust_mentionarray of string required
sampleobject required nullable Every Video of the latest Sample withfocus: { verdict, reason }. Null when the Tracker has no Sample yet (always on a Creator Tracker).atstring required When the latest Sample's Snapshot was taken.statsobject required The full Sample's stats, unchanged by the Focus.sampled_videosinteger requiredviews_totalnumber requiredviews_mediannumber required nullableviews_maxnumber required nullablelikes_totalnumber requiredcomments_totalnumber requiredengagement_ratenumber required nullable
videosarray of object required In-focus and unjudged Videos; withinclude_off_focus=true(and on a preview) every Video, each withfocus.platformstring requiredidstring requiredurlstring required nullabledescriptionstring requiredposted_atstring required nullableduration_secondsnumber required nullablethumbnail_urlstring required nullablesoundobject required nullableidstring requiredtitlestring required nullableis_originalboolean required nullable True for the creator's own audio (a voiceover or original sound), false for a catalogue or library track. Null when the platform did not say, never false for unknown.
creatorobject required nullableidstring requiredhandlestring required nullablenamestring requiredfollower_countnumber required nullableavatar_urlstring required nullable Our archived copy when there is one, else the platform's URL, which may be signed and expire. Download it rather than storing the link.verifiedboolean required nullable The creator's verified badge, from their latest profile read, else from this video's read. Null when neither reported it.
regionstring required nullable Where the video was posted, as the platform reports it (a country code on TikTok). Null when not reported.languagestring required nullable Platform-declared caption language, e.g.en(TikTok). Null when not reported.titlestring required nullable The video's own title (YouTube, Facebook).descriptionstill starts with it on YouTube, as before. Null when the platform shows none or did not report it.commerceobject required nullable Platform-declared commerce: what the Platform itself says, never inferred from the content. Each flag is null when not reported, never false. The object is null when nothing in it was reported.is_adboolean required nullable The Platform marks the video as an ad (TikTok, Instagram).paid_partnershipboolean required nullable The Platform marks a paid partnership (TikTok, Instagram; on YouTube, its "Includes paid promotion" label).affiliateboolean required nullable The Platform marks affiliate content (Instagram).shop_urlstring required nullable The product link the video carries (TikTok Shop).anchorsarray of object required The links the video carries under its caption (an editing template, a product, a place). Empty when none were reported.kindstring required The Platform's own anchor type id, e.g.54.labelstring required What the anchor shows, e.g.CapCut · Editing made easy.
peopleobject required nullable Platform-declared people: accounts the Video itself mentions or names. On TikTokmentionsare the caption's mentions; on Instagram they are the users the Video tags, then the accounts its caption names. Null when it named none.mentionsarray of string required Handles the caption mentions (lowercased).collaboratorsarray of object required Co-authors the Platform names on the Video (an Instagram collab, a Facebook collaborator).handlestring required nullablenamestring required nullable
locationobject required nullable The place the Video names (Instagram). Null when it named none or the read did not say.idstring required nullable The Platform's own place id. Null when not sent.namestring required The place, e.g.Central Park, New York.
topicsobject required nullable Platform-declared topics. Null when the Platform reported none.keywordsarray of string required The creator's own tags (YouTube).genrestring required nullable The Platform's category, e.g.Education(YouTube).labelsarray of string required The Platform's own category labels (TikTok).
chaptersarray of object required nullable The description's chapters, in order (YouTube). Null when the video has none or they were not reported.titlestring requiredstart_secondsnumber required Where the chapter starts, in seconds from the start.
ai_generatedboolean required nullable The Platform labels the video AI-generated (TikTok). Null when not reported.snapshotobject required nullableatstring requiredviewsnumber requiredlikesnumber requiredcommentsnumber requiredsavesnumber required
scoresobject required nullable Null when the creator has no baseline yet.outliernumber required nullable Views over the creator's median views.outlier_p90number required nullablepercentilenumber required nullable Where this video sits in the creator's own sample, 0-100.velocityobject required nullableviews_per_hournumber requiredwindowstring required
reasonstring required nullable alwaysaged_outaged_outwhen the video is over 30 days old and Scores are null.baselineobject required The yardstick every Score on this creator is measured against.median_viewsnumber requiredp90_viewsnumber requiredengagement_ratenumber required nullableposts_per_weeknumber required nullablesampleinteger requiredconfidencestring required one ofhigh,lowsourcestring required one ofvideos,follower_tiercomputed_atstring required nullablestaleboolean required True past 7 days; the next lookup refreshes it.
coveragestring alwayspartialPresent only where the platform's index is best-effort.focusobjectverdictstring required one ofin_focus,off_focus,unjudgedunjudged: the Video could not be judged (or is not judged yet) and is shown.reasonstring required
off_focus_countinteger required Videos hidden as off focus.focusobject requiredtotalinteger required Videos read.in_focusinteger requiredunjudgedinteger required Shown, but not counted in focus.summarystring required "N of M in focus".statsobject required Stats over the in-focus Videos only.sampled_videosinteger requiredviews_totalnumber requiredviews_mediannumber required nullableviews_maxnumber required nullablelikes_totalnumber requiredcomments_totalnumber requiredengagement_ratenumber required nullable
recent_videosobject Only on a Creator Tracker: its newest Videos, every one withfocus: { verdict, reason }.videosarray of object required The Creator's newest Videos, newest first: in-focus and unjudged ones; withinclude_off_focus=trueevery Video, each withfocus.platformstring requiredidstring requiredurlstring required nullabledescriptionstring requiredposted_atstring required nullableduration_secondsnumber required nullablethumbnail_urlstring required nullablesoundobject required nullableidstring requiredtitlestring required nullableis_originalboolean required nullable True for the creator's own audio (a voiceover or original sound), false for a catalogue or library track. Null when the platform did not say, never false for unknown.
creatorobject required nullableidstring requiredhandlestring required nullablenamestring requiredfollower_countnumber required nullableavatar_urlstring required nullable Our archived copy when there is one, else the platform's URL, which may be signed and expire. Download it rather than storing the link.verifiedboolean required nullable The creator's verified badge, from their latest profile read, else from this video's read. Null when neither reported it.
regionstring required nullable Where the video was posted, as the platform reports it (a country code on TikTok). Null when not reported.languagestring required nullable Platform-declared caption language, e.g.en(TikTok). Null when not reported.titlestring required nullable The video's own title (YouTube, Facebook).descriptionstill starts with it on YouTube, as before. Null when the platform shows none or did not report it.commerceobject required nullable Platform-declared commerce: what the Platform itself says, never inferred from the content. Each flag is null when not reported, never false. The object is null when nothing in it was reported.is_adboolean required nullable The Platform marks the video as an ad (TikTok, Instagram).paid_partnershipboolean required nullable The Platform marks a paid partnership (TikTok, Instagram; on YouTube, its "Includes paid promotion" label).affiliateboolean required nullable The Platform marks affiliate content (Instagram).shop_urlstring required nullable The product link the video carries (TikTok Shop).anchorsarray of object required The links the video carries under its caption (an editing template, a product, a place). Empty when none were reported.kindstring required The Platform's own anchor type id, e.g.54.labelstring required What the anchor shows, e.g.CapCut · Editing made easy.
peopleobject required nullable Platform-declared people: accounts the Video itself mentions or names. On TikTokmentionsare the caption's mentions; on Instagram they are the users the Video tags, then the accounts its caption names. Null when it named none.mentionsarray of string required Handles the caption mentions (lowercased).collaboratorsarray of object required Co-authors the Platform names on the Video (an Instagram collab, a Facebook collaborator).handlestring required nullablenamestring required nullable
locationobject required nullable The place the Video names (Instagram). Null when it named none or the read did not say.idstring required nullable The Platform's own place id. Null when not sent.namestring required The place, e.g.Central Park, New York.
topicsobject required nullable Platform-declared topics. Null when the Platform reported none.keywordsarray of string required The creator's own tags (YouTube).genrestring required nullable The Platform's category, e.g.Education(YouTube).labelsarray of string required The Platform's own category labels (TikTok).
chaptersarray of object required nullable The description's chapters, in order (YouTube). Null when the video has none or they were not reported.titlestring requiredstart_secondsnumber required Where the chapter starts, in seconds from the start.
ai_generatedboolean required nullable The Platform labels the video AI-generated (TikTok). Null when not reported.snapshotobject required nullableatstring requiredviewsnumber requiredlikesnumber requiredcommentsnumber requiredsavesnumber required
scoresobject required nullable Null when the creator has no baseline yet.outliernumber required nullable Views over the creator's median views.outlier_p90number required nullablepercentilenumber required nullable Where this video sits in the creator's own sample, 0-100.velocityobject required nullableviews_per_hournumber requiredwindowstring required
reasonstring required nullable alwaysaged_outaged_outwhen the video is over 30 days old and Scores are null.baselineobject required The yardstick every Score on this creator is measured against.median_viewsnumber requiredp90_viewsnumber requiredengagement_ratenumber required nullableposts_per_weeknumber required nullablesampleinteger requiredconfidencestring required one ofhigh,lowsourcestring required one ofvideos,follower_tiercomputed_atstring required nullablestaleboolean required True past 7 days; the next lookup refreshes it.
coveragestring alwayspartialPresent only where the platform's index is best-effort.focusobjectverdictstring required one ofin_focus,off_focus,unjudgedunjudged: the Video could not be judged (or is not judged yet) and is shown.reasonstring required
off_focus_countinteger required Videos hidden as off focus.focusobject requiredtotalinteger required Videos read.in_focusinteger requiredunjudgedinteger required Shown, but not counted in focus.summarystring required "N of M in focus".statsobject required Stats over the in-focus Videos only.sampled_videosinteger requiredviews_totalnumber requiredviews_mediannumber required nullableviews_maxnumber required nullablelikes_totalnumber requiredcomments_totalnumber requiredengagement_ratenumber required nullable
Option 2 object Returned 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_creditsinteger required What the call would be charged, in Credits.cachedboolean required Whether a stored result can already answer. It does not change the price.
401 Unauthorized
missing_authorization, invalid_key, key_revoked, key_expired or invalid_token.
Codes: missing_authorization, invalid_key, key_revoked, key_expired, invalid_token. The problem body and every code are on Errors.
object
RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.
typestring requiredtitlestring requiredstatusinteger requiredcodestring required one ofmissing_authorization,invalid_key,key_revoked,key_expired,invalid_token,organization_not_selected,organization_access_revoked,connection_revoked,forbidden,key_scope_insufficient,invalid_request,unsupported_platform,unsupported_kind,kind_deprecated,focus_unsupported_kind,not_found,comment_not_found,video_too_long,idempotency_conflict,run_not_ready,advertiser_ambiguous,insufficient_balance,max_credits_exceeded,key_spend_cap_exceeded,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.detailstringerrorsarray of object Oninvalid_requestfrom a field that failed validation: one entry per problem, so you can find the field without parsingdetail. Absent when no single field is at fault, e.g. a body that is not JSON.pathstring required Dotted path of the field to fix, e.g.collection_ids.1orcursor. Empty for an issue with the request body as a whole.messagestring required What is wrong with that field.
request_idstring The request this problem answers, the same as itsX-Request-Idheader. Quote it to support.retryableboolean required Whether sending the same request again, after any wait named here, can succeed:truefor a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled;falsewhen the request must change or a person must act. Fixed percode.actionstring required The next step, in one sentence.remedystring What to do next, as the code's error reference page says it; fuller thanaction. On every problem a request answers with; a per-itemerrorinside a result may omit it.retry_after_secondsinteger value at least 0 Seconds to wait before retrying; the same as theRetry-Afterheader. Onrate_limit_exceeded,concurrency_limit_exceeded,source_unavailableandservice_unavailable.expired_atstring When the key expired. Onkey_expired.resets_atstring When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.limitinteger The limit that was hit, on the*_limit_exceededcodes.runninginteger Runs in flight. Onconcurrency_limit_exceeded.activeinteger Active Trackers or webhook endpoints. Ontracker_limit_exceededandwebhook_limit_exceeded.requestedinteger Trackers the request would resume. Ontracker_limit_exceededfrom a Collection action.countinteger Collections held. Oncollection_limit_exceeded.balance_creditsinteger The Balance, in Credits. Oninsufficient_balance.required_creditsinteger What the call needs, in Credits (the worst case where quoted). Oninsufficient_balance.max_creditsinteger The cap the call sent. Onmax_credits_exceeded.estimate_creditsinteger The call's worst-case quote, in Credits. Onmax_credits_exceededandkey_spend_cap_exceeded.cap_creditsinteger The key's monthly cap. Onkey_spend_cap_exceeded.spent_creditsinteger The key's Charges this UTC month. Onkey_spend_cap_exceeded.reserved_creditsinteger What the key's Runs in flight hold. Onkey_spend_cap_exceeded.endpointsarray of string The sources that could not answer. Onsource_unavailable.endpointstring The source that could not answer. Onsource_unavailable.candidatesarray of object The advertisers that carry the name, to ask again with. Onadvertiser_ambiguous.supported_kindsarray of string The kinds that are accepted. Onkind_deprecatedandfocus_unsupported_kind.duration_secondsnumber The video's length. Onvideo_too_long.max_duration_secondsnumber The longest video accepted. Onvideo_too_long.overlap_expires_atstring When the previous secret stops working. Onwebhook_rotation_in_progress.scopestring alwaysread_onlyThe key's scope. Onkey_scope_insufficient.requiredstring alwaysfullThe scope the call needs. Onkey_scope_insufficient.collection_idstring The Collection that already has the name. Oncollection_name_taken.collection_kindstring The Collection's kind. Oncollection_kind_mismatch.kindstring The kind that was offered. Oncollection_kind_mismatch.run_idstring The Run the Idempotency-Key already belongs to. Onidempotency_conflict.reasonstring A short machine-readable reason, where a code has several.reference_idstring Our reference for an unexpected failure, the same asrequest_id; quote it when reporting it.runobject The Run, on a failed Run's body, so its id is kept.idstring requiredkindstring required What was run, e.g.video_lookup.statusstring required one ofrunning,completed,partial,failedpartialkeeps the completed items and charges for them, up to what the Balance covers;failedcharges nothing.created_atstring required RFC 3339.completed_atstring required nullable Null while the Run is still running.charge_creditsinteger required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.list_price_creditsinteger required The full price of the work asked for, in Credits. Equal tocharge_creditsunless the Run charged for only part of it.cachedboolean required True when a stored result answered without a fresh fetch.progressobject What a running Research has done so far, refreshed as it works: itsstageand the counts known by then, such asanalysedofshortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.stagestring required one ofkeywords,searching,reading_creators,filtering,analysing,writing_digestkeywordsinteger value at least 0creatorsinteger value at least 0creators_readinteger value at least 0searchesinteger value at least 0foundinteger value at least 0judgedinteger value at least 0keptinteger value at least 0dropped_off_topicinteger value at least 0dropped_unsureinteger value at least 0shortlistedinteger value at least 0analysedinteger value at least 0updated_atstring required
errorobject The same problem, nested, on a failed Run's body.
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.",
"retryable": false,
"action": "Check the whole key was copied, or create a new key in the console."
}402 Payment Required
insufficient_balance — the Balance cannot cover the quote. Nothing is judged.
Code: insufficient_balance. The problem body and every code are on Errors.
object
RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.
typestring requiredtitlestring requiredstatusinteger requiredcodestring required one ofmissing_authorization,invalid_key,key_revoked,key_expired,invalid_token,organization_not_selected,organization_access_revoked,connection_revoked,forbidden,key_scope_insufficient,invalid_request,unsupported_platform,unsupported_kind,kind_deprecated,focus_unsupported_kind,not_found,comment_not_found,video_too_long,idempotency_conflict,run_not_ready,advertiser_ambiguous,insufficient_balance,max_credits_exceeded,key_spend_cap_exceeded,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.detailstringerrorsarray of object Oninvalid_requestfrom a field that failed validation: one entry per problem, so you can find the field without parsingdetail. Absent when no single field is at fault, e.g. a body that is not JSON.pathstring required Dotted path of the field to fix, e.g.collection_ids.1orcursor. Empty for an issue with the request body as a whole.messagestring required What is wrong with that field.
request_idstring The request this problem answers, the same as itsX-Request-Idheader. Quote it to support.retryableboolean required Whether sending the same request again, after any wait named here, can succeed:truefor a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled;falsewhen the request must change or a person must act. Fixed percode.actionstring required The next step, in one sentence.remedystring What to do next, as the code's error reference page says it; fuller thanaction. On every problem a request answers with; a per-itemerrorinside a result may omit it.retry_after_secondsinteger value at least 0 Seconds to wait before retrying; the same as theRetry-Afterheader. Onrate_limit_exceeded,concurrency_limit_exceeded,source_unavailableandservice_unavailable.expired_atstring When the key expired. Onkey_expired.resets_atstring When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.limitinteger The limit that was hit, on the*_limit_exceededcodes.runninginteger Runs in flight. Onconcurrency_limit_exceeded.activeinteger Active Trackers or webhook endpoints. Ontracker_limit_exceededandwebhook_limit_exceeded.requestedinteger Trackers the request would resume. Ontracker_limit_exceededfrom a Collection action.countinteger Collections held. Oncollection_limit_exceeded.balance_creditsinteger The Balance, in Credits. Oninsufficient_balance.required_creditsinteger What the call needs, in Credits (the worst case where quoted). Oninsufficient_balance.max_creditsinteger The cap the call sent. Onmax_credits_exceeded.estimate_creditsinteger The call's worst-case quote, in Credits. Onmax_credits_exceededandkey_spend_cap_exceeded.cap_creditsinteger The key's monthly cap. Onkey_spend_cap_exceeded.spent_creditsinteger The key's Charges this UTC month. Onkey_spend_cap_exceeded.reserved_creditsinteger What the key's Runs in flight hold. Onkey_spend_cap_exceeded.endpointsarray of string The sources that could not answer. Onsource_unavailable.endpointstring The source that could not answer. Onsource_unavailable.candidatesarray of object The advertisers that carry the name, to ask again with. Onadvertiser_ambiguous.supported_kindsarray of string The kinds that are accepted. Onkind_deprecatedandfocus_unsupported_kind.duration_secondsnumber The video's length. Onvideo_too_long.max_duration_secondsnumber The longest video accepted. Onvideo_too_long.overlap_expires_atstring When the previous secret stops working. Onwebhook_rotation_in_progress.scopestring alwaysread_onlyThe key's scope. Onkey_scope_insufficient.requiredstring alwaysfullThe scope the call needs. Onkey_scope_insufficient.collection_idstring The Collection that already has the name. Oncollection_name_taken.collection_kindstring The Collection's kind. Oncollection_kind_mismatch.kindstring The kind that was offered. Oncollection_kind_mismatch.run_idstring The Run the Idempotency-Key already belongs to. Onidempotency_conflict.reasonstring A short machine-readable reason, where a code has several.reference_idstring Our reference for an unexpected failure, the same asrequest_id; quote it when reporting it.runobject The Run, on a failed Run's body, so its id is kept.idstring requiredkindstring required What was run, e.g.video_lookup.statusstring required one ofrunning,completed,partial,failedpartialkeeps the completed items and charges for them, up to what the Balance covers;failedcharges nothing.created_atstring required RFC 3339.completed_atstring required nullable Null while the Run is still running.charge_creditsinteger required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.list_price_creditsinteger required The full price of the work asked for, in Credits. Equal tocharge_creditsunless the Run charged for only part of it.cachedboolean required True when a stored result answered without a fresh fetch.progressobject What a running Research has done so far, refreshed as it works: itsstageand the counts known by then, such asanalysedofshortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.stagestring required one ofkeywords,searching,reading_creators,filtering,analysing,writing_digestkeywordsinteger value at least 0creatorsinteger value at least 0creators_readinteger value at least 0searchesinteger value at least 0foundinteger value at least 0judgedinteger value at least 0keptinteger value at least 0dropped_off_topicinteger value at least 0dropped_unsureinteger value at least 0shortlistedinteger value at least 0analysedinteger value at least 0updated_atstring required
errorobject The same problem, nested, on a failed Run's body.
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.",
"retryable": false,
"action": "Tell the Customer to top up the Balance, then repeat the same request.",
"balance_credits": 0,
"required_credits": 6
}404 Not Found
not_found.
Code: not_found. The problem body and every code are on Errors.
object
RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.
typestring requiredtitlestring requiredstatusinteger requiredcodestring required one ofmissing_authorization,invalid_key,key_revoked,key_expired,invalid_token,organization_not_selected,organization_access_revoked,connection_revoked,forbidden,key_scope_insufficient,invalid_request,unsupported_platform,unsupported_kind,kind_deprecated,focus_unsupported_kind,not_found,comment_not_found,video_too_long,idempotency_conflict,run_not_ready,advertiser_ambiguous,insufficient_balance,max_credits_exceeded,key_spend_cap_exceeded,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.detailstringerrorsarray of object Oninvalid_requestfrom a field that failed validation: one entry per problem, so you can find the field without parsingdetail. Absent when no single field is at fault, e.g. a body that is not JSON.pathstring required Dotted path of the field to fix, e.g.collection_ids.1orcursor. Empty for an issue with the request body as a whole.messagestring required What is wrong with that field.
request_idstring The request this problem answers, the same as itsX-Request-Idheader. Quote it to support.retryableboolean required Whether sending the same request again, after any wait named here, can succeed:truefor a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled;falsewhen the request must change or a person must act. Fixed percode.actionstring required The next step, in one sentence.remedystring What to do next, as the code's error reference page says it; fuller thanaction. On every problem a request answers with; a per-itemerrorinside a result may omit it.retry_after_secondsinteger value at least 0 Seconds to wait before retrying; the same as theRetry-Afterheader. Onrate_limit_exceeded,concurrency_limit_exceeded,source_unavailableandservice_unavailable.expired_atstring When the key expired. Onkey_expired.resets_atstring When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.limitinteger The limit that was hit, on the*_limit_exceededcodes.runninginteger Runs in flight. Onconcurrency_limit_exceeded.activeinteger Active Trackers or webhook endpoints. Ontracker_limit_exceededandwebhook_limit_exceeded.requestedinteger Trackers the request would resume. Ontracker_limit_exceededfrom a Collection action.countinteger Collections held. Oncollection_limit_exceeded.balance_creditsinteger The Balance, in Credits. Oninsufficient_balance.required_creditsinteger What the call needs, in Credits (the worst case where quoted). Oninsufficient_balance.max_creditsinteger The cap the call sent. Onmax_credits_exceeded.estimate_creditsinteger The call's worst-case quote, in Credits. Onmax_credits_exceededandkey_spend_cap_exceeded.cap_creditsinteger The key's monthly cap. Onkey_spend_cap_exceeded.spent_creditsinteger The key's Charges this UTC month. Onkey_spend_cap_exceeded.reserved_creditsinteger What the key's Runs in flight hold. Onkey_spend_cap_exceeded.endpointsarray of string The sources that could not answer. Onsource_unavailable.endpointstring The source that could not answer. Onsource_unavailable.candidatesarray of object The advertisers that carry the name, to ask again with. Onadvertiser_ambiguous.supported_kindsarray of string The kinds that are accepted. Onkind_deprecatedandfocus_unsupported_kind.duration_secondsnumber The video's length. Onvideo_too_long.max_duration_secondsnumber The longest video accepted. Onvideo_too_long.overlap_expires_atstring When the previous secret stops working. Onwebhook_rotation_in_progress.scopestring alwaysread_onlyThe key's scope. Onkey_scope_insufficient.requiredstring alwaysfullThe scope the call needs. Onkey_scope_insufficient.collection_idstring The Collection that already has the name. Oncollection_name_taken.collection_kindstring The Collection's kind. Oncollection_kind_mismatch.kindstring The kind that was offered. Oncollection_kind_mismatch.run_idstring The Run the Idempotency-Key already belongs to. Onidempotency_conflict.reasonstring A short machine-readable reason, where a code has several.reference_idstring Our reference for an unexpected failure, the same asrequest_id; quote it when reporting it.runobject The Run, on a failed Run's body, so its id is kept.idstring requiredkindstring required What was run, e.g.video_lookup.statusstring required one ofrunning,completed,partial,failedpartialkeeps the completed items and charges for them, up to what the Balance covers;failedcharges nothing.created_atstring required RFC 3339.completed_atstring required nullable Null while the Run is still running.charge_creditsinteger required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.list_price_creditsinteger required The full price of the work asked for, in Credits. Equal tocharge_creditsunless the Run charged for only part of it.cachedboolean required True when a stored result answered without a fresh fetch.progressobject What a running Research has done so far, refreshed as it works: itsstageand the counts known by then, such asanalysedofshortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.stagestring required one ofkeywords,searching,reading_creators,filtering,analysing,writing_digestkeywordsinteger value at least 0creatorsinteger value at least 0creators_readinteger value at least 0searchesinteger value at least 0foundinteger value at least 0judgedinteger value at least 0keptinteger value at least 0dropped_off_topicinteger value at least 0dropped_unsureinteger value at least 0shortlistedinteger value at least 0analysedinteger value at least 0updated_atstring required
errorobject The same problem, nested, on a failed Run's body.
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.",
"retryable": false,
"action": "Check the id or handle; list your resources to find the right one."
}409 Conflict
idempotency_conflict — the same Idempotency-Key with a different payload.
Code: idempotency_conflict. The problem body and every code are on Errors.
object
RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.
typestring requiredtitlestring requiredstatusinteger requiredcodestring required one ofmissing_authorization,invalid_key,key_revoked,key_expired,invalid_token,organization_not_selected,organization_access_revoked,connection_revoked,forbidden,key_scope_insufficient,invalid_request,unsupported_platform,unsupported_kind,kind_deprecated,focus_unsupported_kind,not_found,comment_not_found,video_too_long,idempotency_conflict,run_not_ready,advertiser_ambiguous,insufficient_balance,max_credits_exceeded,key_spend_cap_exceeded,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.detailstringerrorsarray of object Oninvalid_requestfrom a field that failed validation: one entry per problem, so you can find the field without parsingdetail. Absent when no single field is at fault, e.g. a body that is not JSON.pathstring required Dotted path of the field to fix, e.g.collection_ids.1orcursor. Empty for an issue with the request body as a whole.messagestring required What is wrong with that field.
request_idstring The request this problem answers, the same as itsX-Request-Idheader. Quote it to support.retryableboolean required Whether sending the same request again, after any wait named here, can succeed:truefor a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled;falsewhen the request must change or a person must act. Fixed percode.actionstring required The next step, in one sentence.remedystring What to do next, as the code's error reference page says it; fuller thanaction. On every problem a request answers with; a per-itemerrorinside a result may omit it.retry_after_secondsinteger value at least 0 Seconds to wait before retrying; the same as theRetry-Afterheader. Onrate_limit_exceeded,concurrency_limit_exceeded,source_unavailableandservice_unavailable.expired_atstring When the key expired. Onkey_expired.resets_atstring When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.limitinteger The limit that was hit, on the*_limit_exceededcodes.runninginteger Runs in flight. Onconcurrency_limit_exceeded.activeinteger Active Trackers or webhook endpoints. Ontracker_limit_exceededandwebhook_limit_exceeded.requestedinteger Trackers the request would resume. Ontracker_limit_exceededfrom a Collection action.countinteger Collections held. Oncollection_limit_exceeded.balance_creditsinteger The Balance, in Credits. Oninsufficient_balance.required_creditsinteger What the call needs, in Credits (the worst case where quoted). Oninsufficient_balance.max_creditsinteger The cap the call sent. Onmax_credits_exceeded.estimate_creditsinteger The call's worst-case quote, in Credits. Onmax_credits_exceededandkey_spend_cap_exceeded.cap_creditsinteger The key's monthly cap. Onkey_spend_cap_exceeded.spent_creditsinteger The key's Charges this UTC month. Onkey_spend_cap_exceeded.reserved_creditsinteger What the key's Runs in flight hold. Onkey_spend_cap_exceeded.endpointsarray of string The sources that could not answer. Onsource_unavailable.endpointstring The source that could not answer. Onsource_unavailable.candidatesarray of object The advertisers that carry the name, to ask again with. Onadvertiser_ambiguous.supported_kindsarray of string The kinds that are accepted. Onkind_deprecatedandfocus_unsupported_kind.duration_secondsnumber The video's length. Onvideo_too_long.max_duration_secondsnumber The longest video accepted. Onvideo_too_long.overlap_expires_atstring When the previous secret stops working. Onwebhook_rotation_in_progress.scopestring alwaysread_onlyThe key's scope. Onkey_scope_insufficient.requiredstring alwaysfullThe scope the call needs. Onkey_scope_insufficient.collection_idstring The Collection that already has the name. Oncollection_name_taken.collection_kindstring The Collection's kind. Oncollection_kind_mismatch.kindstring The kind that was offered. Oncollection_kind_mismatch.run_idstring The Run the Idempotency-Key already belongs to. Onidempotency_conflict.reasonstring A short machine-readable reason, where a code has several.reference_idstring Our reference for an unexpected failure, the same asrequest_id; quote it when reporting it.runobject The Run, on a failed Run's body, so its id is kept.idstring requiredkindstring required What was run, e.g.video_lookup.statusstring required one ofrunning,completed,partial,failedpartialkeeps the completed items and charges for them, up to what the Balance covers;failedcharges nothing.created_atstring required RFC 3339.completed_atstring required nullable Null while the Run is still running.charge_creditsinteger required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.list_price_creditsinteger required The full price of the work asked for, in Credits. Equal tocharge_creditsunless the Run charged for only part of it.cachedboolean required True when a stored result answered without a fresh fetch.progressobject What a running Research has done so far, refreshed as it works: itsstageand the counts known by then, such asanalysedofshortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.stagestring required one ofkeywords,searching,reading_creators,filtering,analysing,writing_digestkeywordsinteger value at least 0creatorsinteger value at least 0creators_readinteger value at least 0searchesinteger value at least 0foundinteger value at least 0judgedinteger value at least 0keptinteger value at least 0dropped_off_topicinteger value at least 0dropped_unsureinteger value at least 0shortlistedinteger value at least 0analysedinteger value at least 0updated_atstring required
errorobject The same problem, nested, on a failed Run's body.
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.",
"retryable": false,
"action": "Resend the original payload with this key, or use a new key for the new payload.",
"run_id": "run_8f2c1ad04b"
}429 Too Many Requests
rate_limit_exceeded, with Retry-After.
Code: rate_limit_exceeded. The problem body and every code are on Errors.
object
RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.
typestring requiredtitlestring requiredstatusinteger requiredcodestring required one ofmissing_authorization,invalid_key,key_revoked,key_expired,invalid_token,organization_not_selected,organization_access_revoked,connection_revoked,forbidden,key_scope_insufficient,invalid_request,unsupported_platform,unsupported_kind,kind_deprecated,focus_unsupported_kind,not_found,comment_not_found,video_too_long,idempotency_conflict,run_not_ready,advertiser_ambiguous,insufficient_balance,max_credits_exceeded,key_spend_cap_exceeded,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.detailstringerrorsarray of object Oninvalid_requestfrom a field that failed validation: one entry per problem, so you can find the field without parsingdetail. Absent when no single field is at fault, e.g. a body that is not JSON.pathstring required Dotted path of the field to fix, e.g.collection_ids.1orcursor. Empty for an issue with the request body as a whole.messagestring required What is wrong with that field.
request_idstring The request this problem answers, the same as itsX-Request-Idheader. Quote it to support.retryableboolean required Whether sending the same request again, after any wait named here, can succeed:truefor a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled;falsewhen the request must change or a person must act. Fixed percode.actionstring required The next step, in one sentence.remedystring What to do next, as the code's error reference page says it; fuller thanaction. On every problem a request answers with; a per-itemerrorinside a result may omit it.retry_after_secondsinteger value at least 0 Seconds to wait before retrying; the same as theRetry-Afterheader. Onrate_limit_exceeded,concurrency_limit_exceeded,source_unavailableandservice_unavailable.expired_atstring When the key expired. Onkey_expired.resets_atstring When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.limitinteger The limit that was hit, on the*_limit_exceededcodes.runninginteger Runs in flight. Onconcurrency_limit_exceeded.activeinteger Active Trackers or webhook endpoints. Ontracker_limit_exceededandwebhook_limit_exceeded.requestedinteger Trackers the request would resume. Ontracker_limit_exceededfrom a Collection action.countinteger Collections held. Oncollection_limit_exceeded.balance_creditsinteger The Balance, in Credits. Oninsufficient_balance.required_creditsinteger What the call needs, in Credits (the worst case where quoted). Oninsufficient_balance.max_creditsinteger The cap the call sent. Onmax_credits_exceeded.estimate_creditsinteger The call's worst-case quote, in Credits. Onmax_credits_exceededandkey_spend_cap_exceeded.cap_creditsinteger The key's monthly cap. Onkey_spend_cap_exceeded.spent_creditsinteger The key's Charges this UTC month. Onkey_spend_cap_exceeded.reserved_creditsinteger What the key's Runs in flight hold. Onkey_spend_cap_exceeded.endpointsarray of string The sources that could not answer. Onsource_unavailable.endpointstring The source that could not answer. Onsource_unavailable.candidatesarray of object The advertisers that carry the name, to ask again with. Onadvertiser_ambiguous.supported_kindsarray of string The kinds that are accepted. Onkind_deprecatedandfocus_unsupported_kind.duration_secondsnumber The video's length. Onvideo_too_long.max_duration_secondsnumber The longest video accepted. Onvideo_too_long.overlap_expires_atstring When the previous secret stops working. Onwebhook_rotation_in_progress.scopestring alwaysread_onlyThe key's scope. Onkey_scope_insufficient.requiredstring alwaysfullThe scope the call needs. Onkey_scope_insufficient.collection_idstring The Collection that already has the name. Oncollection_name_taken.collection_kindstring The Collection's kind. Oncollection_kind_mismatch.kindstring The kind that was offered. Oncollection_kind_mismatch.run_idstring The Run the Idempotency-Key already belongs to. Onidempotency_conflict.reasonstring A short machine-readable reason, where a code has several.reference_idstring Our reference for an unexpected failure, the same asrequest_id; quote it when reporting it.runobject The Run, on a failed Run's body, so its id is kept.idstring requiredkindstring required What was run, e.g.video_lookup.statusstring required one ofrunning,completed,partial,failedpartialkeeps the completed items and charges for them, up to what the Balance covers;failedcharges nothing.created_atstring required RFC 3339.completed_atstring required nullable Null while the Run is still running.charge_creditsinteger required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.list_price_creditsinteger required The full price of the work asked for, in Credits. Equal tocharge_creditsunless the Run charged for only part of it.cachedboolean required True when a stored result answered without a fresh fetch.progressobject What a running Research has done so far, refreshed as it works: itsstageand the counts known by then, such asanalysedofshortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.stagestring required one ofkeywords,searching,reading_creators,filtering,analysing,writing_digestkeywordsinteger value at least 0creatorsinteger value at least 0creators_readinteger value at least 0searchesinteger value at least 0foundinteger value at least 0judgedinteger value at least 0keptinteger value at least 0dropped_off_topicinteger value at least 0dropped_unsureinteger value at least 0shortlistedinteger value at least 0analysedinteger value at least 0updated_atstring required
errorobject The same problem, nested, on a failed Run's body.
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`.",
"retryable": true,
"action": "Wait `retry_after_seconds`, then retry the same request.",
"limit": 60,
"retry_after_seconds": 12,
"resets_at": "2026-09-08T09:15:00.000Z"
}Related guides
- 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.