Look up an advertiser profile
/v1/advertisers/{library}/{id}One advertiser's profile in one shape on every library: id, url, ad_counts, linked_accounts, domains and freshness, library-only fields under extras.
Meta
- Profile: name, Page URL, running and total Ad counts and
last_observed_at. - Linked accounts: Instagram account and Creator, only when Meta shows the link.
- Fresh lookup: reads and stores every Ad (every status and country) with a Snapshot. Reading to the end 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 (or Meta's total).
- 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; a
truncatedread, normal for a busy advertiser, counts. - Unobserved id: a free 404
not_found. Pass its library URL or name.
- Profile: name,
url,domainswhen known andad_counts.estimate(Google's own;runningandtotalnull), read live. - Target: a domain, or a name several carry, is a free 409
advertiser_ambiguous.
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 |
|---|---|---|---|---|---|
library | path | string one of meta, tiktok, google | Required | — | meta, tiktok or google. |
id | path | string | Required | — | Meta: 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. Google: an AR id, Transparency URL or name. |
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. The same key and payload returns the original Run (202 while running); a different payload or 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 the same inline or 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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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 requiredlibrarystring required one ofmeta,tiktok,googleidstring required Its id in the library: Meta Page id, TikTok advertiser id or GoogleARid.namestring required nullableurlstring required nullable Its library page (Meta: the Page's Ad Library page). TikTok: null until its name is known.ad_countsobject required Meta, TikTok: running and total Ads as last observed, null until a complete observation. Google:estimateonly, Google's own.runninginteger required nullabletotalinteger required nullableestimateinteger required nullable
linked_accountsarray of object required Meta's linked Instagram, TikTok's TikTok account. Empty when the library shows none; never guessed.platformstring required one ofinstagram,tiktokhandlestring required nullable Null, withurl, only when neither the library nor the Creator names it.urlstring required nullabledisplay_namestring required nullablefollowersnumber required nullableverifiedboolean required nullablecreator_idstring required nullable Our Creator behind the account, when we hold one.
domainsarray of string required Domains its newest Ads serve; empty where none are reported.first_seen_atstring requiredlast_observed_atstring required nullable When every Ad of the advertiser was last read in one go.cachedboolean required True when served from a complete observation under 6 hours old. Google: always false.as_ofstring required When this profile was observed.extrasobject required Exactly one key: the advertiser's library.metaobjecttiktokobjectregistry_locationstring required nullablepaid_bystring required nullable
googleobject
page_idstring Deprecated: useid. Meta only.page_urlstring nullable Deprecated. The Facebook Page itself;urlis its Ad Library page. Meta only.instagramobject nullable Deprecated: uselinked_accounts. Meta only.handlestring requiredurlstring required
advertiser_idstring Deprecated: useid. TikTok, Google.tiktok_accountobject nullable Deprecated: uselinked_accounts. TikTok only.creatorobject nullable Deprecated: uselinked_accounts[].creator_id. Meta, TikTok.idstring requiredplatformstring required one ofinstagram,tiktokhandlestring required nullablenamestring required
registry_locationstring nullable Deprecated: useextras.tiktok.registry_location. TikTok only.paid_bystring nullable Deprecated: useextras.tiktok.paid_by. TikTok only.running_ad_countinteger nullable Deprecated: usead_counts.running. Meta, TikTok.total_ad_countinteger nullable Deprecated: usead_counts.total. Meta, TikTok.ad_count_estimateinteger nullable Deprecated: usead_counts.estimate. Google only.
Option 2 object Returned instead of a Run when
estimate=true. Nothing is charged; some operations add members.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 the same inline or polled. Its fields are on Poll or re-read a run.poll_urlstring required formaturiAbsolute URL ofGET /v1/runs/{id}, the body's copy of theLocationheader (for MCP). Present only whilerunning.
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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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 opens and nothing is charged; a multi-item Run that 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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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 answers application/problem+json with its problem's status (vendor_error here, not_found as 404) and the Run envelope, keeping the Run id. Never charged. The example is a Video lookup's.
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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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": "video_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, envelope alongside; endpoints names the source. Retry after retry_after_seconds (also Retry-After); it does not mean empty. The example is a Video lookup's.
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,feature_unavailable,not_analysable,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.featurestring The switched-off option, e.g.download. Onfeature_unavailable.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 A running Research'sstageand counts so far, such asanalysedofshortlisted; a count is absent until known. Absent once the Run settles and on other kinds.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": "video_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, TikTok's and Google's ad libraries: the filters, what each Ad carries, the winner Score, Ad analysis, what is stored, and what a search costs.