Skip to content
For AI agents: a documentation index is available at /llms.txt. Every docs page is also available as markdown: add .md to its URL. To connect, read /agents.md.
ShortsIntel
Create a key

API referenceTrackers

List stored Ads

Open in ClaudeOpen in ChatGPT
GET /v1/trackers/{id}/ads

Every Ad stored for this Advertiser Tracker, paused too, with no Run: stopped and removed Ads included, newest start first, unknown starts last. Filters skip Ads with no value. Other kinds answer unsupported_kind.

Each Ad carries analysis { summary, hook_type, angle, offer_type, format }, or null. The analysis filters skip Ads with none.

Price

Free.

Parameters

NameInTypeRequiredDefaultDescription
idpathstring Required—Tracker id.
statusquerystring one of active, inactive, allOptionalallinactive includes removed Ads. Only all keeps Ads whose state is unknown.
countryquerystring Optional—ISO-2. Matches the newest observation that named countries. Meta names none for commercial Ads, so those never match.
started_afterquerystring Optional—ISO date, inclusive.
started_beforequerystring Optional—ISO date, exclusive.
stopped_afterquerystring Optional—ISO date, inclusive.
stopped_beforequerystring Optional—ISO date, exclusive.
media_typequerystring one of video, image, carouselOptional—The Ad's format.
hook_typequerystring one of QUESTION, BOLD_CLAIM, PROBLEM, STORY, DEMONSTRATION, LISTICLE, CONTROVERSY, SOCIAL_PROOF, CURIOSITY_GAP, DIRECT_ADDRESS, NONEOptional—Image Ads have no hook, so they never match.
anglequerystring one of PROBLEM_SOLUTION, BENEFIT, SOCIAL_PROOF, SCARCITY_URGENCY, PRICE_VALUE, AUTHORITY, CURIOSITY, TRANSFORMATION, FEAR_OF_MISSING_OUT, COMPARISON, STORY, ANNOUNCEMENT, OTHEROptional—Video Ads analysed before this field never match.
offer_typequerystring one of DISCOUNT, FREE_TRIAL, FREE_SHIPPING, FREE_GIFT, BUNDLE, LIMITED_TIME, GUARANTEE, LEAD_MAGNET, NONEOptional—NONE is an Ad with no offer found. Video Ads analysed before this field never match.
formatquerystring one of TALKING_HEAD, VOICEOVER_BROLL, SCREEN_RECORDING, TUTORIAL, UNBOXING, BEFORE_AFTER, SKIT, VLOG, SLIDESHOW, GREEN_SCREEN, SPLIT_SCREEN, COMPILATION, PRODUCT_DEMO, OTHER, PRODUCT_SHOT, LIFESTYLE, UGC_STYLE, TESTIMONIAL, INFOGRAPHIC, TEXT_ONLY, MEME, SCREENSHOT, COLLAGE, ILLUSTRATIONOptional—The production format, on image and video Ads.
min_days_runningqueryinteger min 0; max 99999Optional—Least days_running. A removed Ad's days end at its removal when no stop date was read. A stopped Ad with no stop or removal date has none, so it never matches.
includequerystring one of intelligenceOptional—intelligence adds each Ad's full analysis.
limitqueryinteger min 1; max 100Optional25Items per page.
cursorquerystring Optional—Opaque next_cursor from the previous page.

Responses

200 OK

{ items, next_cursor }.

object

A page of a list. items holds the page; pass next_cursor back as cursor for the next one.

  • next_cursor string required nullable Pass back as cursor. Null on the last page.
  • items array of object required
    • library string required one of meta, tiktok, google
    • id string required
    • url string required nullable
    • advertiser object required
      • id string required nullable
      • name string required nullable
    • is_active boolean required nullable False once stopped or removed. Null when no observation says.
    • first_shown string required nullable
    • last_shown string required nullable
    • placements array of string required
    • creative object required
      • title string required nullable
      • body string required nullable
      • cta string required nullable
      • format string required nullable
      • image_urls array of string required
      • video_urls array of string required
      • thumbnail_urls array of string required
    • reach object required Ranges as the library reports them, never coerced. Meta discloses spend and impressions for political and issue Ads, and reach (audience) for some EU Ads; otherwise null. TikTok reports audience (a bucket such as 10K-100K); spend is null, and impressions is null except on a single-Ad lookup.
      • impressions string required nullable
      • spend string required nullable
      • currency string required nullable
      • audience string required nullable
    • kind string nullable one of commercial, political, issue Meta and Google.
    • media_type string required nullable one of video, image, carousel Meta and TikTok. Null when not stored.
    • countries array of string required nullable Null on Meta commercial Ads and unread TikTok details.
    • variant_count number nullable Meta only. How many Ads share this Ad's media; null for a single Ad.
    • days_running integer required nullable Start to stop, else to removal, else to now. Null with no start, or when an Ad known stopped has no stop or removal date.
    • variations array of object Google only. Each version of the Ad's copy and media. A video Ad's YouTube id sits here when Google shows one, which not every video Ad has; creative.video_urls stays empty.
      • headline string required nullable
      • description string required nullable
      • all_text string required nullable
      • destination_url string required nullable
      • visible_url string required nullable
      • image_urls array of string required
      • video_id string required nullable
      • youtube_url string required nullable
    • details_failed boolean Google search only. True when this Ad's details could not be read: it holds only the list row and is not charged or stored.
    • archived boolean True when every media URL is our permanent archived copy; false while any is still the library's expiring URL (retried on the next sighting).
    • winner_score object nullable Meta only. How strongly the Ad looks like a winner. 0 to 100, computed from the stored history of the Ad, never fetched. score = round(100 x (0.7 x rank(days_running) + 0.3 x rank(variants_added))), where rank is the share of the Advertiser's other Ads below this one (ties count half) and variants_added is the variant count at the latest Snapshot minus at the first. With one Snapshot the score is round(100 x rank(days_running)), confidence low, reason single_snapshot. With no other dated Ad of the Advertiser, rank falls back to min(days, 90)/90 and min(variants, 5)/5; under 5 dated Ads of the Advertiser the score is low confidence, reason few_advertiser_ads. No start date: score null, reason no_start_date.
      • score number required nullable
      • confidence string required one of high, low
      • inputs object required
        • days_running number required nullable
        • variants_added number required
        • snapshots number required
        • advertiser_ads number required Dated Ads of this Advertiser stored so far, this one included.
      • reason string required nullable one of single_snapshot, few_advertiser_ads, no_start_date
    • intelligence any of 2 shapes nullable Only with include=intelligence. Null with none stored.
      • Option 1 object Video Ads: the full video analysis, read from the archived video with the ad copy as context, plus offer, copy, and detected shots, the product's first appearance and the opening frame under structure.
        • version integer required
        • model string required
        • computed_at string required
        • source string required
        • content object required
          • summary string required
          • niche string required
          • languages array of string required
          • content_styles array of string required
          • keywords array of object required
            • keyword string required
            • category string required
            • sentiment number required
          • transcript string required nullable What is said, one line per line: the Platform's captions or speech-to-text, never the scene breakdown. Empty with no speech; null when it could not be read.
          • transcript_source string required nullable one of caption, whisper caption: the Platform's caption track. whisper: speech-to-text on the audio. Null when transcript is null, and on analysis stored before 2026-11-09.
          • transcript_segments array of object required nullable Timed transcript lines (ms from the start), to see when the hook lands. From the Platform's timed captions when it has them, otherwise measured from the video's audio with speech-to-text. Spoken timing here is measured; times in structure.scenes are approximate. Empty when the video has no speech, music-only videos included. Null when the timing could not be measured, on a YouTube Video with no captions, and on older analyses.
            • start_ms integer required
            • end_ms integer required
            • text string required
        • hook object required
          • opening_line string required nullable
          • type string required
          • visual_hook string required nullable
          • rationale string required nullable
        • persuasion object required
          • call_to_action object required
            • type string required
            • text string required nullable
          • sponsored boolean required Whether the video is plausibly a paid promotion. Always true when the Platform labels it an ad or a paid partnership.
          • sponsorship_signals array of string required
          • brands_and_products array of object required
            • name string required
            • kind string required
            • prominence string required
          • trend_references array of object required
            • name string required
            • kind string required
        • tone object required
          • sentiment_label string required
          • sentiment_score number required
          • primary_emotion string required
          • emotion_intensity number required nullable
          • emotion_rationale string required nullable
          • speaking_style string required
          • speaking_style_notes string required nullable
        • visual object required
          • format string required
          • setting string required
          • face_visibility string required
          • on_screen_text array of string required
          • has_on_screen_captions boolean required
          • camera_notes string required nullable
          • lighting_notes string required nullable
          • elements any
        • safety object required
          • brand_safety_tier string required
          • reasons array of string required
          • notes string required nullable
        • structure object required When things happen inside the creative: the timed scenes every analysis carries, plus the shots detected, when the product is first seen and the opening frame on a video Ad.
          • scenes array of object required The timed scenes, read from the stored scene breakdown. Times are approximate, to about a second. Empty when the breakdown has no timed scenes, as on a photo carousel.
            • start_ms integer required Approximate scene start, ms from the start.
            • end_ms integer required Approximate scene end, ms from the start.
            • visual string required nullable
            • text_overlay string required nullable Text shown in this scene, listed at its first appearance: text repeated from an earlier scene is left out.
            • speech string required nullable
            • audio string required nullable Notable sound effects or music.
          • shots array of object required nullable The detected shots in order, each from one cut to the next. A cut is a frame whose ffmpeg scene score is over 0.2. On 29 labelled Ads this found 86% of hard cuts within 500 ms (median error 67 ms) and 61% of jump cuts overall, but none on UGC Ads. Null when detection failed, and on analysis stored before shots.
            • start_ms integer required Shot start: the cut before it, or 0.
            • end_ms integer required Shot end: the next cut, or the video's end.
          • cuts_per_minute number required nullable Detected cuts per minute of video, to two decimals. Null whenever shots is.
          • avg_shot_ms integer required nullable The video's length over its number of shots, in ms. Null whenever shots is.
          • product_first_seen_ms integer required nullable When the promoted product first appears (the item, its packaging or logo, or an app's screen), as the start of that scene in ms, so approximate to one scene. On 26 labelled Ads that show one, it was within 3 s of the labelled time on 23 (88%). Null when no product is shown, and on analysis stored before it.
          • first_frame string required nullable What the video's opening frame shows, as text: a description, not a time. Read from the first scene's **Opening Frame:** line in the scene breakdown. Checked against the video on 10 Ads, it was accurate on all 10. Null when the breakdown has no opening frame, and on analysis stored before it.
        • pipeline string required always video
        • offer object required nullable The offer, in the same types as an image Ad's offer. Null when the extraction failed and on analysis stored before this field.
          • type string required
          • text string required nullable
        • copy object required nullable The persuasion angle, in the same values as an image Ad's copy.angle. Null when the extraction failed and on analysis stored before this field.
          • angle string required
          • rationale string required nullable
      • Option 2 object Image and carousel Ads: the analysis an image can carry, read from the archived images with the ad copy as context.
        • pipeline string required always image
        • version integer required
        • model string required
        • computed_at string required
        • images_analyzed integer required
        • summary string required
        • copy object required
          • angle string required
          • rationale string required nullable
          • headline string required nullable
        • offer object required
          • type string required
          • text string required nullable
        • call_to_action object required
          • type string required
          • text string required nullable
        • visual object required
          • format string required
          • on_image_text array of string required
        • topics array of string required
        • tone object required
          • sentiment_label string required
          • sentiment_score number required
    • intelligence_error object Why analyze left intelligence null: no analysis charge. Its fields are on Errors.
    • advertiser_account object nullable TikTok lookup only. The TikTok account the Ad ran from.
      • username string required
      • display_name string required nullable
      • followers string required nullable As TikTok shows it (9.3M), not a number.
      • verified boolean required nullable
      • url string required nullable
    • targeting object nullable TikTok lookup only. Where and to whom the ad library says the Ad was delivered, impressions as ranges per country by age and gender. Null when the Ad came from Creative Center.
      • countries array of string required
      • impressions string required nullable
      • audience_size string required nullable
      • ages array of string required Age ranges targeted (18-24).
      • genders array of string required Genders targeted (female, male, unknown).
      • by_country array of object required
        • country string required
        • impressions string required nullable
        • breakdown array of object required
          • age string required
          • gender string required
          • impressions string required nullable
    • performance object nullable TikTok lookup only. Creative Center's engagement figures, when the Ad is a Creative Center Top Ad; null for an Ad only the ad library holds.
      • ctr number required nullable Click-through rate as a fraction (0.46 is 46%).
      • likes number required nullable
      • comments number required nullable
      • shares number required nullable
    • objective string nullable TikTok lookup only. The Ad's objective (Traffic).
    • stopped_at string required nullable TikTok infers it from the last day shown.
    • removed_from_library boolean required
    • removed_at string required nullable When we first found the Ad gone from the library.
    • analysis object required nullable Null when the Ad has no stored analysis.
      • summary string required
      • hook_type string required nullable Null on image Ads.
      • angle string required nullable Null on older video Ads.
      • offer_type string required nullable NONE: no offer found. Null on older video Ads.
      • format string required

400 Bad Request

invalid_request for a cursor that is not a next_cursor this API issued. Nothing is charged.

Code: invalid_request. 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.

  • type string required
  • title string required
  • status integer required
  • code string required one of missing_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_error Stable machine-readable code.
  • detail string
  • errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
    • path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
    • message string required What is wrong with that field.
  • request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
  • retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
  • action string required The next step, in one sentence.
  • remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
  • retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
  • expired_at string When the key expired. On key_expired.
  • resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
  • limit integer The limit that was hit, on the *_limit_exceeded codes.
  • running integer Runs in flight. On concurrency_limit_exceeded.
  • active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
  • requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
  • count integer Collections held. On collection_limit_exceeded.
  • balance_credits integer The Balance, in Credits. On insufficient_balance.
  • required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
  • max_credits integer The cap the call sent. On max_credits_exceeded.
  • estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
  • cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
  • spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
  • reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
  • endpoints array of string The sources that could not answer. On source_unavailable.
  • endpoint string The source that could not answer. On source_unavailable.
  • candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
  • supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
  • duration_seconds number The video's length. On video_too_long.
  • max_duration_seconds number The longest video accepted. On video_too_long.
  • overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
  • scope string always read_only The key's scope. On key_scope_insufficient.
  • required string always full The scope the call needs. On key_scope_insufficient.
  • collection_id string The Collection that already has the name. On collection_name_taken.
  • collection_kind string The Collection's kind. On collection_kind_mismatch.
  • kind string The kind that was offered. On collection_kind_mismatch.
  • run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
  • reason string A short machine-readable reason, where a code has several.
  • reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
  • run object The Run, on a failed Run's body, so its id is kept.
    • id string required
    • kind string required What was run, e.g. video_lookup.
    • status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
    • created_at string required RFC 3339.
    • completed_at string required nullable Null while the Run is still running.
    • charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    • list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
    • cached boolean required True when a stored result answered without a fresh fetch.
    • progress object What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • stage string required one of keywords, searching, reading_creators, filtering, analysing, writing_digest
      • keywords integer value at least 0
      • creators integer value at least 0
      • creators_read integer value at least 0
      • searches integer value at least 0
      • found integer value at least 0
      • judged integer value at least 0
      • kept integer value at least 0
      • dropped_off_topic integer value at least 0
      • dropped_unsure integer value at least 0
      • shortlisted integer value at least 0
      • analysed integer value at least 0
      • updated_at string required
  • error object 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": "`cursor` is not a cursor this API issued. Pass back the `next_cursor` from the previous page.",
  "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.

  • type string required
  • title string required
  • status integer required
  • code string required one of missing_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_error Stable machine-readable code.
  • detail string
  • errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
    • path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
    • message string required What is wrong with that field.
  • request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
  • retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
  • action string required The next step, in one sentence.
  • remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
  • retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
  • expired_at string When the key expired. On key_expired.
  • resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
  • limit integer The limit that was hit, on the *_limit_exceeded codes.
  • running integer Runs in flight. On concurrency_limit_exceeded.
  • active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
  • requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
  • count integer Collections held. On collection_limit_exceeded.
  • balance_credits integer The Balance, in Credits. On insufficient_balance.
  • required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
  • max_credits integer The cap the call sent. On max_credits_exceeded.
  • estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
  • cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
  • spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
  • reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
  • endpoints array of string The sources that could not answer. On source_unavailable.
  • endpoint string The source that could not answer. On source_unavailable.
  • candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
  • supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
  • duration_seconds number The video's length. On video_too_long.
  • max_duration_seconds number The longest video accepted. On video_too_long.
  • overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
  • scope string always read_only The key's scope. On key_scope_insufficient.
  • required string always full The scope the call needs. On key_scope_insufficient.
  • collection_id string The Collection that already has the name. On collection_name_taken.
  • collection_kind string The Collection's kind. On collection_kind_mismatch.
  • kind string The kind that was offered. On collection_kind_mismatch.
  • run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
  • reason string A short machine-readable reason, where a code has several.
  • reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
  • run object The Run, on a failed Run's body, so its id is kept.
    • id string required
    • kind string required What was run, e.g. video_lookup.
    • status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
    • created_at string required RFC 3339.
    • completed_at string required nullable Null while the Run is still running.
    • charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    • list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
    • cached boolean required True when a stored result answered without a fresh fetch.
    • progress object What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • stage string required one of keywords, searching, reading_creators, filtering, analysing, writing_digest
      • keywords integer value at least 0
      • creators integer value at least 0
      • creators_read integer value at least 0
      • searches integer value at least 0
      • found integer value at least 0
      • judged integer value at least 0
      • kept integer value at least 0
      • dropped_off_topic integer value at least 0
      • dropped_unsure integer value at least 0
      • shortlisted integer value at least 0
      • analysed integer value at least 0
      • updated_at string required
  • error object 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."
}

404 Not Found

not_found — also a deleted Tracker, or another Customer's.

Code: not_found. The problem body and every code are on Errors.

object

RFC 9457 problem document, served as application/problem+json. Branch on code, never on the prose. retryable and action say whether to retry and what to do next.

  • type string required
  • title string required
  • status integer required
  • code string required one of missing_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_error Stable machine-readable code.
  • detail string
  • errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
    • path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
    • message string required What is wrong with that field.
  • request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
  • retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
  • action string required The next step, in one sentence.
  • remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
  • retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
  • expired_at string When the key expired. On key_expired.
  • resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
  • limit integer The limit that was hit, on the *_limit_exceeded codes.
  • running integer Runs in flight. On concurrency_limit_exceeded.
  • active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
  • requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
  • count integer Collections held. On collection_limit_exceeded.
  • balance_credits integer The Balance, in Credits. On insufficient_balance.
  • required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
  • max_credits integer The cap the call sent. On max_credits_exceeded.
  • estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
  • cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
  • spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
  • reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
  • endpoints array of string The sources that could not answer. On source_unavailable.
  • endpoint string The source that could not answer. On source_unavailable.
  • candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
  • supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
  • duration_seconds number The video's length. On video_too_long.
  • max_duration_seconds number The longest video accepted. On video_too_long.
  • overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
  • scope string always read_only The key's scope. On key_scope_insufficient.
  • required string always full The scope the call needs. On key_scope_insufficient.
  • collection_id string The Collection that already has the name. On collection_name_taken.
  • collection_kind string The Collection's kind. On collection_kind_mismatch.
  • kind string The kind that was offered. On collection_kind_mismatch.
  • run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
  • reason string A short machine-readable reason, where a code has several.
  • reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
  • run object The Run, on a failed Run's body, so its id is kept.
    • id string required
    • kind string required What was run, e.g. video_lookup.
    • status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
    • created_at string required RFC 3339.
    • completed_at string required nullable Null while the Run is still running.
    • charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    • list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
    • cached boolean required True when a stored result answered without a fresh fetch.
    • progress object What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • stage string required one of keywords, searching, reading_creators, filtering, analysing, writing_digest
      • keywords integer value at least 0
      • creators integer value at least 0
      • creators_read integer value at least 0
      • searches integer value at least 0
      • found integer value at least 0
      • judged integer value at least 0
      • kept integer value at least 0
      • dropped_off_topic integer value at least 0
      • dropped_unsure integer value at least 0
      • shortlisted integer value at least 0
      • analysed integer value at least 0
      • updated_at string required
  • error object The same problem, nested, on a failed Run's body.

404 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No such resource for this Customer.",
  "retryable": false,
  "action": "Check the id or handle; list your resources to find the right one."
}

422 Unprocessable Content

unsupported_kind — not an Advertiser Tracker. Nothing is run or charged.

Code: unsupported_kind. 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.

  • type string required
  • title string required
  • status integer required
  • code string required one of missing_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_error Stable machine-readable code.
  • detail string
  • errors array of object On invalid_request from a field that failed validation: one entry per problem, so you can find the field without parsing detail. Absent when no single field is at fault, e.g. a body that is not JSON.
    • path string required Dotted path of the field to fix, e.g. collection_ids.1 or cursor. Empty for an issue with the request body as a whole.
    • message string required What is wrong with that field.
  • request_id string The request this problem answers, the same as its X-Request-Id header. Quote it to support.
  • retryable boolean required Whether sending the same request again, after any wait named here, can succeed: true for a rate or concurrency limit, an upstream outage, an internal error or a Run not yet settled; false when the request must change or a person must act. Fixed per code.
  • action string required The next step, in one sentence.
  • remedy string What to do next, as the code's error reference page says it; fuller than action. On every problem a request answers with; a per-item error inside a result may omit it.
  • retry_after_seconds integer value at least 0 Seconds to wait before retrying; the same as the Retry-After header. On rate_limit_exceeded, concurrency_limit_exceeded, source_unavailable and service_unavailable.
  • expired_at string When the key expired. On key_expired.
  • resets_at string When the request window (rate_limit_exceeded) or the key's month (key_spend_cap_exceeded) resets.
  • limit integer The limit that was hit, on the *_limit_exceeded codes.
  • running integer Runs in flight. On concurrency_limit_exceeded.
  • active integer Active Trackers or webhook endpoints. On tracker_limit_exceeded and webhook_limit_exceeded.
  • requested integer Trackers the request would resume. On tracker_limit_exceeded from a Collection action.
  • count integer Collections held. On collection_limit_exceeded.
  • balance_credits integer The Balance, in Credits. On insufficient_balance.
  • required_credits integer What the call needs, in Credits (the worst case where quoted). On insufficient_balance.
  • max_credits integer The cap the call sent. On max_credits_exceeded.
  • estimate_credits integer The call's worst-case quote, in Credits. On max_credits_exceeded and key_spend_cap_exceeded.
  • cap_credits integer The key's monthly cap. On key_spend_cap_exceeded.
  • spent_credits integer The key's Charges this UTC month. On key_spend_cap_exceeded.
  • reserved_credits integer What the key's Runs in flight hold. On key_spend_cap_exceeded.
  • endpoints array of string The sources that could not answer. On source_unavailable.
  • endpoint string The source that could not answer. On source_unavailable.
  • candidates array of object The advertisers that carry the name, to ask again with. On advertiser_ambiguous.
  • supported_kinds array of string The kinds that are accepted. On kind_deprecated and focus_unsupported_kind.
  • duration_seconds number The video's length. On video_too_long.
  • max_duration_seconds number The longest video accepted. On video_too_long.
  • overlap_expires_at string When the previous secret stops working. On webhook_rotation_in_progress.
  • scope string always read_only The key's scope. On key_scope_insufficient.
  • required string always full The scope the call needs. On key_scope_insufficient.
  • collection_id string The Collection that already has the name. On collection_name_taken.
  • collection_kind string The Collection's kind. On collection_kind_mismatch.
  • kind string The kind that was offered. On collection_kind_mismatch.
  • run_id string The Run the Idempotency-Key already belongs to. On idempotency_conflict.
  • reason string A short machine-readable reason, where a code has several.
  • reference_id string Our reference for an unexpected failure, the same as request_id; quote it when reporting it.
  • run object The Run, on a failed Run's body, so its id is kept.
    • id string required
    • kind string required What was run, e.g. video_lookup.
    • status string required one of running, completed, partial, failed partial keeps the completed items and charges for them, up to what the Balance covers; failed charges nothing.
    • created_at string required RFC 3339.
    • completed_at string required nullable Null while the Run is still running.
    • charge_credits integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    • list_price_credits integer required The full price of the work asked for, in Credits. Equal to charge_credits unless the Run charged for only part of it.
    • cached boolean required True when a stored result answered without a fresh fetch.
    • progress object What a running Research has done so far, refreshed as it works: its stage and the counts known by then, such as analysed of shortlisted. A count is absent until its stage produced it. Absent once the Run settles, and on every other kind.
      • stage string required one of keywords, searching, reading_creators, filtering, analysing, writing_digest
      • keywords integer value at least 0
      • creators integer value at least 0
      • creators_read integer value at least 0
      • searches integer value at least 0
      • found integer value at least 0
      • judged integer value at least 0
      • kept integer value at least 0
      • dropped_off_topic integer value at least 0
      • dropped_unsure integer value at least 0
      • shortlisted integer value at least 0
      • analysed integer value at least 0
      • updated_at string required
  • error object The same problem, nested, on a failed Run's body.

422 · Example

{
  "type": "https://www.shortsintel.com/docs/reference/errors/unsupported_kind",
  "title": "Unsupported kind",
  "status": 422,
  "code": "unsupported_kind",
  "detail": "Stored Ads are read from Advertiser Trackers, not creator Trackers.",
  "retryable": false,
  "action": "Do not repeat this request; nothing was charged. Use an operation that serves this kind."
}
  • Pagination: Following next_cursor through a list.
  • Trackers: Standing watches on a creator or an Advertiser: how a cycle runs, when it reports a change, and how to pause one.

Request samples

Use ShortsIntel to list stored Ads.

- id: trk_4b1e90c7aa
- status: all
- media_type: video
- hook_type: QUESTION
- angle: PROBLEM_SOLUTION
- offer_type: DISCOUNT
- format: TALKING_HEAD
- include: intelligence
- limit: 25

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

If you don't have ShortsIntel tools, don't guess: read https://www.shortsintel.com/agents.md, follow it to connect, then retry this request.

200 · `{ items, next_cursor }`.

{
  "items": [
    {
      "library": "meta",
      "id": "2233445566778899",
      "url": "https://www.facebook.com/ads/library/?id=2233445566778899",
      "advertiser": {
        "id": "100064000000001",
        "name": "Plunge"
      },
      "is_active": false,
      "first_shown": "2026-06-02T00:00:00.000Z",
      "last_shown": "2026-07-14T00:00:00.000Z",
      "placements": [
        "INSTAGRAM"
      ],
      "creative": {
        "title": "Three minutes. Every morning.",
        "body": "Our coldest tub yet, now in matte black.",
        "cta": "Learn More",
        "link_url": "https://plunge.example/black",
        "format": "IMAGE",
        "image_urls": [
          "https://cdn.shortsintel.com/ads/plunge-black.jpg"
        ],
        "video_urls": [],
        "thumbnail_urls": []
      },
      "reach": {
        "impressions": null,
        "spend": null,
        "currency": null,
        "audience": null
      },
      "kind": "commercial",
      "media_type": "image",
      "countries": [
        "US",
        "CA"
      ],
      "variant_count": 3,
      "days_running": 42,
      "archived": true,
      "stopped_at": "2026-07-14T00:00:00.000Z",
      "removed_from_library": true,
      "removed_at": "2026-09-20T08:00:00.000Z",
      "analysis": {
        "summary": "A matte black cold plunge tub shown in a bright bathroom.",
        "hook_type": null,
        "angle": "BENEFIT",
        "offer_type": "NONE",
        "format": "PRODUCT_SHOT"
      }
    }
  ],
  "next_cursor": "eyJzIjoiMjAyNi0wNi0wMlQwMDowMDowMC4wMDBaIiwibCI6IjEifQ"
}