# Get a TikTok Ad

> For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md).

GET `/v1/ads/tiktok/{ad_id}`

One TikTok Ad by its ad library id: a search result plus landing page, CTA, objective, advertiser id, its TikTok account (`advertiser_account`) and `targeting`. EU/EEA, Swiss, UK and Turkish Ads only.

- Targeting: countries, ages, genders, impressions per country by age and gender.
- Fallback: when the library cannot answer, Creative Center may. `targeting` is then null and `performance` has CTR, likes, comments and shares.
- Nulls: unpublished fields are null, never zero.
- Storage: stored with archived media. Served from our copy within 6 hours, or with `removed_from_library: true` once dropped, at the same price. `as_of` says when it was last observed.
- Analysis: `analyze=true` adds Ad analysis (the video set for a video Ad, the image set for an image or carousel Ad), computed once per Ad and version from our archived media with the ad copy as context.
- Analysis timing: when it must be computed expect a 202 and poll. If it fails the Run fails, uncharged.
- Stored analysis: free on every lookup, whether `analyze` or a Tracker computed it.
- Analysis on the fallback: a Creative Center answer has no library Ad and no archived media, so `analyze` fails the Run with `media_unavailable` (`reason: creative_center`), uncharged. The same lookup without `analyze` returns the Ad.
- Errors: unknown id is 404 `not_found` and an unreachable library is `source_unavailable`. Neither is charged.

[Open in Playground](https://www.shortsintel.com/console/playground?op=getTikTokAd&ad_id=ad_id_example&analyze=true) (no API Key needed)

## Price

3 credits. With `analyze=true`, plus 20 credits, whether the analysis is computed or already stored.

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 |
| --- | --- | --- | --- | --- | --- |
| `ad_id` | path | `string` | Required | — | The TikTok ad library id: the number in `library.tiktok.com/ads/detail/?ad_id=...`, or an `id` from a TikTok `POST /ads/search`. |
| `analyze` | query | `string` one of `true`, `false` | Optional | — | `true` to add Ad analysis: 20 credits, computed or already stored. |
| `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 }`.

any of 2 shapes

- Option 1 object The envelope every charged operation answers with: `{ run }` while the Run is running (plus `poll_url` on the 202), joined by `result` once it completes or `error` once it fails.
  - `run` object required Every charged operation creates a Run; the envelope is the same inline or polled.
    - `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 A running Research's `stage` and counts so far, such as `analysed` of `shortlisted`; a count is absent until known. Absent once the Run settles and on other kinds.
      - `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
  - `result` object required
    - `ad` 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
      - `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
        - `link_url` 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 nullable one of `video`, `image`, `carousel`, `text` Meta and Google (`video`, `image`, `text`).
      - `countries` array of string nullable Countries reached, when the library discloses them: Meta and Google search and lookup, and the TikTok single-Ad lookup.
      - `variant_count` number nullable Meta only. How many Ads share this Ad's media; null for a single Ad.
      - `days_running` number nullable Meta only. Whole days from start to stop, or to now while running.
      - `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 Present when already computed for this Ad, or asked for with `analyze`; null under `analyze` when it could not be computed.
        - 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 captions. `whisper`: speech-to-text. Null with a null `transcript` and on analyses before 2026-11-09.
            - `transcript_segments` array of object required nullable Timed lines (ms from the start), to see when the hook lands: the Platform's timed captions, else speech-to-text on the audio. Measured, unlike the approximate `structure.scenes`. Empty with no speech; null when not measured (a YouTube Video without captions, 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 Timed scenes from the scene breakdown, approximate to about a second. Empty when it has none, 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, at its first appearance only.
              - `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](https://www.shortsintel.com/docs/reference/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`).
      - `removed_from_library` boolean required True when the library's own detail read answered not found for the Ad; it is then served from our stored copy, at the same price.
      - `removed_at` string required nullable When this API first found the Ad gone from the library.
    - `as_of` string required nullable When the Ad was last observed in the library. Null for a Creative Center answer, which is not stored.
- Option 2 object Returned instead of a Run when `estimate=true`. Nothing is charged; some operations add members.
  - `estimate_credits` integer required What the call would be charged, in Credits.
  - `cached` boolean 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.

- `run` object 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](https://www.shortsintel.com/docs/reference/runs/get-run#response-200).
- `poll_url` string required format `uri` Absolute URL of `GET /v1/runs/{id}`, the body's copy of the `Location` header (for MCP). Present only while `running`.

202 · Example

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "ad_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](https://www.shortsintel.com/docs/reference/errors).

### 401 Unauthorized

Codes: `missing_authorization`, `invalid_key`, `key_revoked`, `key_expired`, `invalid_token`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 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](https://www.shortsintel.com/docs/reference/errors).

### 409 Conflict

`idempotency_conflict` — the same Idempotency-Key with a different payload.

Code: `idempotency_conflict`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 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](https://www.shortsintel.com/docs/reference/errors).

### 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](https://www.shortsintel.com/docs/reference/errors).

### 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](https://www.shortsintel.com/docs/reference/errors).

## 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}`](https://www.shortsintel.com/docs/reference/runs/get-run) until it settles; re-reading a Run is free.

- [Runs](https://www.shortsintel.com/docs/concepts/runs): How a call becomes a Run, waiting inline, polling and free re-reads.
- [Pricing and estimates](https://www.shortsintel.com/docs/concepts/pricing-and-estimates): Credits, estimates and why a cached result costs the same as a fresh one.
- [Ads](https://www.shortsintel.com/docs/concepts/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

curl:

```bash
curl "https://www.shortsintel.com/v1/ads/tiktok/ad_id_example?analyze=true&wait=30" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

TypeScript:

```typescript
const response = await fetch(
  "https://www.shortsintel.com/v1/ads/tiktok/ad_id_example?analyze=true&wait=30",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();
```

Python:

```python
import requests

response = requests.get(
    "https://www.shortsintel.com/v1/ads/tiktok/ad_id_example?analyze=true&wait=30",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()
```

200 · The Run finished inside the wait budget: `{ run, result }`.

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "ad_lookup",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 3,
    "list_price_credits": 3,
    "cached": false
  },
  "result": {
    "ad": {
      "library": "tiktok",
      "id": "1879578150853938",
      "url": "https://library.tiktok.com/ads/detail/?ad_id=1879578150853938",
      "advertiser": {
        "id": "6876453864464188162",
        "name": "Northpeak Outdoor GmbH"
      },
      "is_active": null,
      "first_shown": "2026-10-20T00:00:00.000Z",
      "last_shown": "2026-10-22T00:00:00.000Z",
      "placements": [],
      "creative": {
        "title": "New winter gear, in store now.",
        "body": null,
        "cta": "Learn more",
        "link_url": "https://www.example.com/winter",
        "format": null,
        "image_urls": [],
        "video_urls": [
          "https://library.tiktok.com/api/v1/cdn/1792740803/video/..."
        ],
        "thumbnail_urls": [
          "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/..."
        ]
      },
      "reach": {
        "impressions": "100K-200K",
        "spend": null,
        "currency": null,
        "audience": "100K-200K"
      },
      "countries": [
        "DE"
      ],
      "advertiser_account": {
        "username": "northpeak",
        "display_name": "Northpeak",
        "followers": "1.2M",
        "verified": true,
        "url": "https://www.tiktok.com/@northpeak"
      },
      "targeting": {
        "countries": [
          "DE"
        ],
        "impressions": "100K-200K",
        "audience_size": "15.2M-18.6M",
        "ages": [
          "18-24",
          "25-34",
          "35-44"
        ],
        "genders": [
          "female",
          "male",
          "unknown"
        ],
        "by_country": [
          {
            "country": "DE",
            "impressions": "124K",
            "breakdown": [
              {
                "age": "18-24",
                "gender": "female",
                "impressions": "34K"
              }
            ]
          }
        ]
      },
      "performance": null,
      "objective": "Traffic",
      "archived": true,
      "removed_from_library": false,
      "removed_at": null
    },
    "as_of": "2026-10-23T09:12:58.104Z"
  }
}
```

200 · With `estimate=true`: the price, no Run, no charge.

```json
{
  "estimate_credits": 3,
  "cached": false
}
```

[Previous Look up a Meta Ad by id](https://www.shortsintel.com/docs/reference/ads/get-meta-ad)[Next Look up a Google Ad](https://www.shortsintel.com/docs/reference/ads/get-google-ad)
