Look up an advertiser profile
/v1/advertisers/{page_id}One advertiser's profile, from the Meta library or, with library=tiktok, the TikTok one.
Meta
- Advertiser: a Facebook Page that runs Ads.
- Profile: name, Page URL, running and total Ad counts as last observed, and
last_observed_at. - Linked accounts: its linked Instagram account and Creator, only when Meta shows the link, never guessed from the name.
- Fresh lookup: reads and stores every Ad (every status and country) with a Snapshot. Reading to the end is a complete observation, which stamps the counts.
- Stored results: for 6 hours after that, the profile and any
advertisersearch on it are served from storage, sayingcachedandas_of. - Large advertisers: one with more Ads than a lookup reads keeps its last complete counts (and Meta's own total when reported).
- No Ads in the library: 404
not_found, free.
TikTok
- Profile: TikTok account, registry location, paid by and counts (running: active, shown in the past 3 days). Its Ads are stored and archived.
- Complete observation: unless the library broke it off part-way.
- Truncated reads: a
truncatedread counts, serving the profile for 6 hours. It is normal for a busy advertiser, because the library's paging skips Ads shown the same day. - Unobserved id: a bare TikTok id we have not observed yet is 404
not_found, free, because the library needs the exact name beside it. Pass its library URL or name.
Open in Playground (no API Key needed)
Price
15 credits, the same when served within 6 hours of a complete observation.
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 |
|---|---|---|---|---|---|
page_id | path | string | Required | — | The numeric Facebook Page id (from a name or Page URL, search with advertiser first). TikTok: an advertiser id, library URL or name; several matches 409 advertiser_ambiguous, none 404. |
library | query | string one of meta, tiktok | Optional | meta | meta (default) or tiktok. |
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
resultany of 2 shapes requiredOption 1 object
page_idstring required The Facebook Page id: the advertiser's identity.namestring required nullablepage_urlstring required nullableinstagramobject required nullable The Page's linked Instagram account, only when Meta shows one.handlestring requiredurlstring required
creatorobject required nullable The Creator behind that Instagram account, when we hold one. Never guessed from the name.idstring requiredplatformstring required alwaysinstagramhandlestring required nullablenamestring required
running_ad_countinteger required nullable Running Ads as last observed; null until a complete observation.total_ad_countinteger required nullable Every Ad the Page has in the library, running or stopped, as last observed.last_observed_atstring required nullable When every Ad of the advertiser was last read in one go.first_seen_atstring requiredcachedboolean required True when served from a complete observation under 6 hours old.as_ofstring required When this profile was observed.
Option 2 object
namestring required nullablerunning_ad_countinteger required nullable Running Ads as last observed; null until a complete observation.total_ad_countinteger required nullable Every Ad the Page has in the library, running or stopped, as last observed.last_observed_atstring required nullable When every Ad of the advertiser was last read in one go.first_seen_atstring requiredcachedboolean required True when served from a complete observation under 6 hours old.as_ofstring required When this profile was observed.librarystring required alwaystiktokadvertiser_idstring required The library's advertiser id.urlstring required nullabletiktok_accountobject required nullableusernamestring requireddisplay_namestring required nullablefollowersstring required nullable As TikTok shows it (9.3M), not a number.verifiedboolean required nullableurlstring required nullable
creatorobject required nullableidstring requiredplatformstring required alwaystiktokhandlestring required nullablenamestring required
registry_locationstring required nullablepaid_bystring 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.
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": "advertiser_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 15 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": 15
}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": "advertiser_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": "advertiser_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.
- Ads: Search Meta's and TikTok's ad libraries by keyword or advertiser: the filters, what each Ad carries, the winner Score, Ad analysis, what is stored, and what a search costs.