Look up a hashtag's trend
/v1/hashtags/{platform}/{tag}Stats, trend direction and top videos, with a Snapshot written every time so the next lookup has something to compare against.
Open in Playground (no API Key needed)
Price
3 credits, the same when a Snapshot under 24 h old can answer.
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 |
|---|---|---|---|---|---|
platform | path | string one of tiktok, instagram | Required | — | Platform the subject lives on. |
tag | path | string | Required | — | Tag without the #. |
wait | query | integer min 0; max 120 | Optional | 30 | Seconds to hold the response open before handing back a running Run to poll. Default 30, max 120. A POST may send it in the body instead; different values in both places are a 400. |
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. |
estimate | query | boolean | Optional | — | true returns { estimate_credits, cached } from what is already stored, creating no Run. Nothing is charged. If a source the call would read is unavailable and the cache cannot answer, the estimate adds unavailable (the { platform, capability } parts it cannot reach), or is a 503 source_unavailable when it can reach none. Only true or false, else a 400. A POST may send it in the body instead; different values in both places are a 400. |
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. |
Responses
200 OK
The Run finished inside the wait budget: { run, result }. With estimate=true, { estimate_credits, cached } instead.
any of 2 shapes
Option 1 object The envelope every charged operation answers with:
{ run }while the Run is running (pluspoll_urlon the 202), joined byresultonce it completes orerroronce it fails.runobject required Every charged operation creates a Run. The envelope is identical whether the result came back inline or was polled.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
resultobject requiredplatformstring requiredtagstring requiredurlstring required nullableplatform_idstring required nullable The platform's own id for the tag, as its videos report it. TikTok only; null on Instagram or when no video reported it.descriptionstring required nullable The platform's description of the tag, as its videos report it. TikTok only; null on Instagram or when none was given.statsobject requiredsampled_videosinteger requiredviews_totalnumber requiredviews_mediannumber required nullableviews_maxnumber required nullablelikes_totalnumber requiredcomments_totalnumber requiredengagement_ratenumber required nullable
trendobject required Movement between the two most recent Snapshots.directionstring required nullable one ofrising,falling,flatchange_rationumber required nullablesincestring required nullable
snapshotobject requiredatstring requiredsampled_videosinteger requiredviews_totalnumber requiredviews_mediannumber required nullableviews_maxnumber required nullablelikes_totalnumber requiredcomments_totalnumber requiredengagement_ratenumber required nullable
top_videosarray of object requiredplatformstring 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.
coveragestring alwayspartial
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.
202 Accepted
Still running: { run }. Poll GET /v1/runs/{id}.
object
Still running. Poll poll_url (GET /v1/runs/{id}), waiting the 202's Retry-After seconds between polls.
runobject required Every charged operation creates a Run. The envelope is identical whether the result came back inline or was polled. Its fields are on Poll or re-read a run.poll_urlstring required formaturiAbsolute URL ofGET /v1/runs/{id}for this Run, the body's copy of the 202'sLocationheader for callers that never see headers (MCP). Present only while the Run isrunning.
202 · Example
{
"run": {
"id": "run_8f2c1ad04b",
"kind": "hashtag_lookup",
"status": "running",
"created_at": "2026-09-08T09:14:02.418Z",
"completed_at": null,
"charge_credits": 0,
"list_price_credits": 0,
"cached": false
},
"poll_url": "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b"
}400 Bad Request
invalid_request (a malformed id, wait, estimate or Idempotency-Key) or unsupported_platform, refused before any Run opens. Nothing is charged.
Codes: invalid_request, unsupported_platform. 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.
400 · Example
{
"type": "https://www.shortsintel.com/docs/reference/errors/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "`estimate` must be `true` or `false`.",
"retryable": false,
"action": "Fix the field named in `detail`, then send the corrected request."
}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 quoted price (the worst case for Research and enriched search). No Run is created and nothing is charged. A multi-item Run whose Balance runs short later charges its completed items up to the Balance and ends partial.
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 3 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": 3
}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 or concurrency_limit_exceeded, with Retry-After.
Codes: rate_limit_exceeded, concurrency_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"
}502 Bad Gateway
A Run that opened and then failed is answered as application/problem+json with its problem's status — vendor_error here, not_found as 404 — and the Run envelope alongside, so the Run id is kept. A failed Run is never charged.
Code: vendor_error. 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.
502 · Example
{
"type": "https://www.shortsintel.com/docs/reference/errors/vendor_error",
"title": "Vendor error",
"status": 502,
"code": "vendor_error",
"detail": "The upstream data provider could not be reached.",
"retryable": true,
"action": "Retry with a backoff; nothing was charged.",
"run": {
"id": "run_8f2c1ad04b",
"kind": "hashtag_lookup",
"status": "failed",
"created_at": "2026-09-08T09:14:02.418Z",
"completed_at": "2026-09-08T09:14:04.930Z",
"charge_credits": 0,
"list_price_credits": 0,
"cached": false
}
}503 Service Unavailable
source_unavailable: every source this Run reads failed or is switched off. The Run fails uncharged, with its envelope alongside; endpoints names the source. Wait retry_after_seconds (also sent as Retry-After) and retry rather than treating it as empty.
Code: source_unavailable. 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.
503 · Example
{
"type": "https://www.shortsintel.com/docs/reference/errors/source_unavailable",
"title": "Source unavailable",
"status": 503,
"code": "source_unavailable",
"detail": "The tiktok/video source is unavailable right now.",
"retryable": true,
"action": "Wait `retry_after_seconds`, then retry; do not treat this as an empty result.",
"endpoints": [
"tiktok/video"
],
"run": {
"id": "run_8f2c1ad04b",
"kind": "hashtag_lookup",
"status": "failed",
"created_at": "2026-09-08T09:14:02.418Z",
"completed_at": "2026-09-08T09:14:04.930Z",
"charge_credits": 0,
"list_price_credits": 0,
"cached": false
},
"retry_after_seconds": 60
}Related guides
This call creates a Run. With wait it holds the response open until the Run finishes or the wait runs out, then answers with the finished result or 202 and the running Run. Poll GET /v1/runs/{id} until it settles; re-reading a Run is free.
- Runs: How a call becomes a Run, waiting inline, polling and free re-reads.
- Pricing and estimates: Credits, estimates and why a cached result costs the same as a fresh one.
- Addressing videos and creators: Naming a video, creator, hashtag or sound.