> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok ads

> Read a TikTok Ad Library search page with an adv_name keyword or advertiser as JSON with the tiktok-ads parser. $1 per 1,000 calls.

Reads a TikTok Ad Library search page with an adv\_name keyword or advertiser, or an ad page, and returns its data as JSON.

## Make a request

Send the page's URL to [scrape](https://docs.stophy.dev/api-reference/endpoint/scrape.md) with a `json` format that names the parser. Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://library.tiktok.com/ads?region=DE&adv_name=adidas&query_type=1","formats":[{"type":"json","parser":"tiktok-ads"}]}'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://library.tiktok.com/ads?region=DE&adv_name=adidas&query_type=1",
    formats: [{ type: "json", parser: "tiktok-ads" }],
  }),
});
console.log(await response.json());
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://library.tiktok.com/ads?region=DE&adv_name=adidas&query_type=1",
        "formats": [{"type": "json", "parser": "tiktok-ads"}],
    },
)
print(response.json())
```

## Read the response

The parser's data is in `data.json`. Its fields include `adId`, `adUrl`, `advertiserName`, `headline`, `firstShownAt` and `lastShownAt`. This sample is cut to the first items.

```json theme={null}
{
  "success": true,
  "data": {
    "json": {
      "results": [
        {
          "adId": "1871324448424097",
          "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1871324448424097",
          "advertiserName": "adidas AG",
          "headline": "adidas Hyperboost Euphoria",
          "firstShownAt": "2026-07-30T00:00:00.000Z",
          "lastShownAt": "2026-08-19T00:00:00.000Z",
          "reachMin": 1000000,
          "reachMax": 10000000,
          "videoUrl": "https://library.tiktok.com/api/v1/cdn/1793833904/video/aHR0cHM6Ly92NzcudGlrdG9rY2RuLmNvbS9iZGQ3MjhjMGE4ZGM1ODQ3YzI4YWM2…",
          "thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o45ljvYzEkiDA0dAUAy8mEiUBVCYs3aAhIaos~tplv-tiktokx-origin…",
          "imageUrls": [
            "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o45ljvYzEkiDA0dAUAy8mEiUBVCYs3aAhIaos~tplv-tiktokx-origin…"
          ]
        }
      ],
      "total": null,
      "cursor": "eyJsYXN0X3NvcnQiOlszMC41MzQyNTIsMTc4NzA5NzYwMDAwMF0sIm5leHRfY3Vyc29yIjoxMn0=~ifbul0fcf5.ifeb8tduky.ifeb8tdulu.ifbu48choh.ifeb8tdsyq.ifjx2ki5k2.ifbtkmpele.ifk..."
    }
  }
}
```

## Options

Send options in the `options` object of the `json` format.

| Option | What it does |
| - | - |
| `advertiser` | An advertiser name. TikTok matches the name exactly, so use it as tiktok.ads.ad gives it, like Nike, Inc. When no listed advertiser has exactly this name, the closest listed name is used. Send this or query, not both. |
| `cursor` | The cursor from the previous response. Send it as is. |

## Price

\$1 per 1,000 calls. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Limits and errors

* The URL must be a TikTok Ad Library search page with an adv\_name keyword or advertiser, or an ad page. Any other URL fails with `invalidRequest`.
* To read the next page, send the `cursor` from the response as the `cursor` option. Paging needs an API key.
* The answer comes back in `data.json`. If the page cannot be read, the call fails with an error code from [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Related

* [Pre-built parsers](https://docs.stophy.dev/scrape/prebuilt-parsers) lists every parser.
* [Scrape](https://docs.stophy.dev/scrape/overview) has the options every scrape takes.
* [TikTok video](https://docs.stophy.dev/scrape/prebuilt-parsers/video/tiktok-video.md)
* [TikTok comments](https://docs.stophy.dev/scrape/prebuilt-parsers/video/tiktok-comments.md)
* [TikTok transcript](https://docs.stophy.dev/scrape/prebuilt-parsers/video/tiktok-transcript.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.