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 referenceAds

Get a TikTok Ad's analysis

Open in ClaudeOpen in ChatGPT
GET /v1/ads/tiktok/{ad_id}/intelligence

The Ad's latest stored analysis, as an earlier analyze or a Tracker with intelligence computed it. Nothing is computed here: an Ad with none yet is not_found; ask for it with analyze. Shared across Customers.

Open in Playground (no API Key needed)

Price

Free.

Parameters

NameInTypeRequiredDefaultDescription
ad_idpathstring Required—The TikTok ad library id.

Responses

200 OK

{ library_id, intelligence }.

object

  • library_id string required
  • intelligence any of 2 shapes required Ad analysis, versioned and computed once per Ad and version. pipeline says which set it is.
    • 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

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.

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": "This Ad has no analysis yet. Request it with `analyze: true`.",
  "retryable": false,
  "action": "Check the id or handle; list your resources to find the right 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.

Request samples

Use ShortsIntel to get a TikTok Ad's analysis.

- ad_id: ad_id_example

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 · `{ library_id, intelligence }`.

{
  "library_id": "2233445566778899",
  "intelligence": {
    "pipeline": "image",
    "version": 1,
    "model": "gemini-3.5-flash-lite",
    "computed_at": "2026-09-21T10:02:11.000Z",
    "images_analyzed": 1,
    "summary": "A matte black cold plunge tub shot in a bright bathroom, sold on a daily three-minute routine.",
    "copy": {
      "angle": "TRANSFORMATION",
      "rationale": "The headline frames the tub as a daily ritual and the copy as an upgrade.",
      "headline": "Three minutes. Every morning."
    },
    "offer": {
      "type": "NONE",
      "text": null
    },
    "call_to_action": {
      "type": "VISIT_SITE",
      "text": "Learn More"
    },
    "visual": {
      "format": "PRODUCT_SHOT",
      "on_image_text": [
        "Three minutes. Every morning."
      ]
    },
    "topics": [
      "cold plunge",
      "morning routine",
      "home wellness"
    ],
    "tone": {
      "sentiment_label": "POSITIVE",
      "sentiment_score": 0.6
    }
  }
}