Name: TikTok Ads Library API: Ad Creatives and Advertisers
Brand: s-r
SKU: api-s-r-tiktok-ads-library
Availability: InStock
Author: API Market

# TikTok Ads Library API

## Overview

The TikTok Ads Library API searches TikTok's public Ads Library and returns the ads as JSON. Each row has the advertiser name, ad text, image and video URLs, first and last shown dates, days shown, region and whether the ad is active or stopped.

It is built for marketers, agencies and ad-intelligence tools that track competitors' creative on TikTok. Search by advertiser name or keyword, by TikTok's advertiser business ID, or look up one ad by its ID, then filter by region, status and dates and page through larger result sets.

## Features

*   **2 endpoints**: the same search as `POST /run` with a JSON body or `GET /run` with query parameters.
*   **3 ways to search**: advertiser name or keyword, advertiser business ID, or ad ID.
*   **Full creative**: ad text, image and video URLs for every ad.
*   **Run dates**: first and last shown dates and days shown.
*   **Filters**: region, active or stopped status and a date window.
*   **Pagination**: `limit` and `offset`, or continue with `search_id`.
*   **Rate limit**: 10 requests per second on Free and Basic, 20 on Pro, 50 on Plus.

## Use Cases

*   **Competitor creative**: see what ads a brand runs on TikTok.
*   **Ad archives**: save creatives before they disappear.
*   **Market watch**: track which advertisers run ads in a country.
*   **Creative research**: find how long an ad stayed live.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/s-r/tiktok-ads-library
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Search ads (POST)

Returns ads that match the search in the JSON body.

**Method:** `POST`

**Endpoint:** `/run`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| search | body | Advertiser name or keyword (e.g. "nike", "korean skincare"). One of search / ad_id / adv_biz_ids is required. | string | No | - | - |
| ad_id | body | Look up one ad by its ID. This short-circuits the whole run: nothing is fetched from TikTok and the search query, region, dates, sort, limit and offset are all ignored. The single row it returns carries the ad id and a deeplink and no ad content, because TikTok publishes no ad-detail API to read it from. | string | No | - | - |
| adv_biz_ids | body | TikTok's own advertiser business ID. It is sent in the search body next to the query, so TikTok narrows on it rather than the rows being filtered here. It does not replace Search query: whatever is in that box is still sent alongside, so clear it if you want the advertiser on its own. One of search, ad_id or this is needed to start a run. | string | No | - | - |
| region | body | ISO country code or 'all'. Note: TikTok Ad Library does NOT support region=US - use 'all' to include US ads in the global result set. | string | No | all | - |
| query_type | body | 1 = by advertiser name, 0 = by keyword. | string | No | 1 | - |
| sort | body | Order results by recency or impression count. | string | No | last_shown_date,desc | - |
| ad_status | body | Stopped creative is a record of what an advertiser tried and dropped, and it is usually the larger half. Measured on one Dutch retailer: 12 ads running against 681 stopped. | string | No | active | - |
| only_total | body | Return one row with how many ads match and no ads at all. Costs one request and no per-ad charge. TikTok caps the reported figure at 5000, and the row says whether the number is exact or a floor. | boolean | No | false | - |
| start_date | body | Lower bound of the search window, written YYYY-MM-DD. It becomes the start_time parameter on TikTok's own search call, so TikTok applies it and a narrower window means fewer pages to walk. Left empty it defaults to one year before the run. An Ad ID lookup ignores it. | string | No | - | - |
| end_date | body | Upper bound of the search window, written YYYY-MM-DD. Like the lower bound it is sent as a parameter on TikTok's own search call rather than applied to the rows afterwards. Left empty it defaults to the moment the run starts, and an Ad ID lookup ignores it. | string | No | - | - |
| limit | body | How many ads to collect. TikTok serves 12 per response, so higher values walk the cursor further and take longer. | integer | No | 20 | 25 |
| offset | body | Result offset for pagination. | integer | No | 0 | - |
| search_id | body | Continue a previous run from the `_next_search_id` value it wrote on its rows, paired with the Pagination offset from the same rows. The API already walks the cursor by itself up to Number of ads, so this is only for going past where an earlier run stopped, not for reaching a higher count in one go. Leave empty to start a fresh search. | string | No | - | - |
| cursor | body | Signed continuation from next_cursor. Keep search filters unchanged. | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/s-r/tiktok-ads-library/run' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "search": "coolblue",
  "region": "NL",
  "limit": 3
}'
```

**Example Response (200 OK):**

```json
{
  "data": {
    "total_ads_in_search": 56,
    "pages_fetched": 1,
    "_next_search_id": "eyJsYXN0X3NvcnQiOlsyNC44NzU1LDE3OTM3NTA0MDAwMDBdLCJuZXh0X2N1cnNvciI6M30=",
    "_next_offset": 3,
    "items": [
      {
        "ad_id": "1879757706954945",
        "advertiser_name": "Coolblue B.V.",
        "audit_status": "approved",
        "ad_type": "video",
        "first_shown": "2026-10-25",
        "last_shown": "2026-11-04",
        "days_shown": 11,
        "estimated_audience": "1M-10M",
        "impression": 0,
        "spent": "",
        "deeplink": "https://library.tiktok.com/ads/detail/?ad_id=1879757706954945",
        "result_type": "ad",
        "_type": "ad_creative",
        "fetched_at": "2026-11-05T21:00:34.513Z",
        "ad_text": "Was elke dag gratis als je overstapt naar Coolblue Energie.",
        "source": "tiktok-ads-library",
        "platform": "tiktok",
        "videos": [
          {
            "video_url": "https://library.tiktok.com/api/v1/cdn/1793912446/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvdXNlYXN0MmEvdG9zLXVzZWFzdDJhLXZlLTAwNTFjNzk5LWV1dHRwL293UkV3aTFGbXFUSTFBOWZWYTJhcnZTNU9NSkJCQWlOb0RQQTJYLw==/af2c6fc1-f6fe-44e9-9382-82d5...",
            "cover_image": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ooQDVqAqbmbfGCsG8fUDJu5AEWgjrZ1IcAfFb6~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=61ac73a6&x-expires=1793934000&x-signature=5EeqfprEyklyK3SHsJMYi7Dfoys%3D&t=4d5b0474&ps=1374..."
          }
        ],
        "image_urls": [
          "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ooQDVqAqbmbfGCsG8fUDJu5AEWgjrZ1IcAfFb6~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=61ac73a6&x-expires=1793934000&x-signature=5EeqfprEyklyK3SHsJMYi7Dfoys%3D&t=4d5b0474&ps=1374..."
        ],
        "creative_id": "1879757706954945",
        "format": "video",
        "days_active": 11,
        "text": "Was elke dag gratis als je overstapt naar Coolblue Energie.",
        "first_seen": "2026-10-25",
        "last_seen": "2026-11-04",
        "image_url": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/ooQDVqAqbmbfGCsG8fUDJu5AEWgjrZ1IcAfFb6~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=61ac73a6&x-expires=1793934000&x-signature=5EeqfprEyklyK3SHsJMYi7Dfoys%3D&t=4d5b0474&ps=1374...",
        "video_url": "https://library.tiktok.com/api/v1/cdn/1793912446/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvdXNlYXN0MmEvdG9zLXVzZWFzdDJhLXZlLTAwNTFjNzk5LWV1dHRwL293UkV3aTFGbXFUSTFBOWZWYTJhcnZTNU9NSkJCQWlOb0RQQTJYLw==/af2c6fc1-f6fe-44e9-9382-82d5...",
        "query": "coolblue",
        "region": "NL",
        "sort": "last_shown_date,desc",
        "ad_status": "active",
        "region_code": "NL",
        "total_ads_in_search": 56,
        "pages_fetched": 1,
        "_next_search_id": "eyJsYXN0X3NvcnQiOlsyNC44NzU1LDE3OTM3NTA0MDAwMDBdLCJuZXh0X2N1cnNvciI6M30=",
        "_next_offset": 3
      },
      {
        "ad_id": "1880469737667458",
        "advertiser_name": "Coolblue B.V.",
        "audit_status": "approved",
        "ad_type": "video",
        "first_shown": "2026-10-30",
        "last_shown": "2026-11-04",
        "days_shown": 6,
        "estimated_audience": "1K-10K",
        "impression": 0,
        "spent": "",
        "deeplink": "https://library.tiktok.com/ads/detail/?ad_id=1880469737667458",
        "result_type": "ad",
        "_type": "ad_creative",
        "fetched_at": "2026-11-05T21:00:34.513Z",
        "ad_text": "",
        "source": "tiktok-ads-library",
        "platform": "tiktok",
        "videos": [
          {
            "video_url": "https://library.tiktok.com/api/v1/cdn/1793912446/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvdXNlYXN0MmEvdG9zLXVzZWFzdDJhLXZlLTAwNjgtZXV0dHAvb3NCV0F5aDV1RnZWZ0VHZ1FxRURsN2ZpSVdWZlFVMUhEbUlGMVIv/a09c520c-dc5f-46e7-b93a-31710b439430...",
            "cover_image": "https://p16-common-sign.tiktokcdn.com/tos-useast2a-p-0037-euttp/o8cCBcCzOIAjwCrD6xZKkfCGxoiywABj1E6IGi~tplv-noop.image?dr=18692&refresh_token=a847aa3e&x-expires=1793934094&x-signature=G0JAOFYY8BSE%2F2dNdEHmGPLxeBs%3D&t=9276707c&ps=14f1eb3e&..."
          }
        ],
        "creative_id": "1880469737667458",
        "format": "video",
        "days_active": 6,
        "text": "",
        "first_seen": "2026-10-30",
        "last_seen": "2026-11-04",
        "video_url": "https://library.tiktok.com/api/v1/cdn/1793912446/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvdXNlYXN0MmEvdG9zLXVzZWFzdDJhLXZlLTAwNjgtZXV0dHAvb3NCV0F5aDV1RnZWZ0VHZ1FxRURsN2ZpSVdWZlFVMUhEbUlGMVIv/a09c520c-dc5f-46e7-b93a-31710b439430...",
        "query": "coolblue",
        "region": "NL",
        "sort": "last_shown_date,desc",
        "ad_status": "active",
        "region_code": "NL",
        "total_ads_in_search": 56,
        "pages_fetched": 1,
        "_next_search_id": "eyJsYXN0X3NvcnQiOlsyNC44NzU1LDE3OTM3NTA0MDAwMDBdLCJuZXh0X2N1cnNvciI6M30=",
        "_next_offset": 3
      }
    ],
    "billing": {
      "scraped": 3
    },
    "next_cursor": "eyJ2ZXJzaW9uIjoxLCJmaWx0ZXJzIjoiW1wiY29vbGJsdWVcIixcIlwiLFwiTkxcIixcIjFcIixcImxhc3Rfc2hvd25fZGF0ZSxkZXNjXCIsXCJhY3RpdmVcIixcIlwiLFwiXCJdIiwic3RhcnRfdGltZSI6MTc2MjM3NjQzNCwiZW5kX3RpbWUiOjE3OTM5MTI0MzQsInNlYXJjaF9pZCI6ImV5SnNZWE4wWDNOdmNuUWlP...",
    "partial": true,
    "warnings": [
      "More ads remain; continue with next_cursor."
    ],
    "errors": []
  },
  "meta": {
    "request_id": "ed8d4d8e-7593-4097-aa7c-0a7281ed8caa",
    "duration_ms": 12802,
    "units": 3,
    "cached": false
  }
}
```

#### 2. Search ads (GET)

The same search with query parameters. It returns the same rows as the POST endpoint.

**Method:** `GET`

**Endpoint:** `/run`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| search | query | Advertiser name or keyword (e.g. "nike", "korean skincare"). One of search / ad_id / adv_biz_ids is required. | string | No | - | - |
| ad_id | query | Look up one ad by its ID. This short-circuits the whole run: nothing is fetched from TikTok and the search query, region, dates, sort, limit and offset are all ignored. The single row it returns carries the ad id and a deeplink and no ad content, because TikTok publishes no ad-detail API to read it from. | string | No | - | - |
| adv_biz_ids | query | TikTok's own advertiser business ID. It is sent in the search body next to the query, so TikTok narrows on it rather than the rows being filtered here. It does not replace Search query: whatever is in that box is still sent alongside, so clear it if you want the advertiser on its own. One of search, ad_id or this is needed to start a run. | string | No | - | - |
| region | query | ISO country code or 'all'. Note: TikTok Ad Library does NOT support region=US - use 'all' to include US ads in the global result set. | string | No | all | - |
| query_type | query | 1 = by advertiser name, 0 = by keyword. | string | No | 1 | - |
| sort | query | Order results by recency or impression count. | string | No | last_shown_date,desc | - |
| ad_status | query | Stopped creative is a record of what an advertiser tried and dropped, and it is usually the larger half. Measured on one Dutch retailer: 12 ads running against 681 stopped. | string | No | active | - |
| only_total | query | Return one row with how many ads match and no ads at all. Costs one request and no per-ad charge. TikTok caps the reported figure at 5000, and the row says whether the number is exact or a floor. | boolean | No | false | - |
| start_date | query | Lower bound of the search window, written YYYY-MM-DD. It becomes the start_time parameter on TikTok's own search call, so TikTok applies it and a narrower window means fewer pages to walk. Left empty it defaults to one year before the run. An Ad ID lookup ignores it. | string | No | - | - |
| end_date | query | Upper bound of the search window, written YYYY-MM-DD. Like the lower bound it is sent as a parameter on TikTok's own search call rather than applied to the rows afterwards. Left empty it defaults to the moment the run starts, and an Ad ID lookup ignores it. | string | No | - | - |
| limit | query | How many ads to collect. TikTok serves 12 per response, so higher values walk the cursor further and take longer. | integer | No | 20 | 25 |
| offset | query | Result offset for pagination. | integer | No | 0 | - |
| search_id | query | Continue a previous run from the `_next_search_id` value it wrote on its rows, paired with the Pagination offset from the same rows. The API already walks the cursor by itself up to Number of ads, so this is only for going past where an earlier run stopped, not for reaching a higher count in one go. Leave empty to start a fresh search. | string | No | - | - |
| cursor | query | Signed continuation from next_cursor. Keep search filters unchanged. | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/s-r/tiktok-ads-library/run?search=coolblue&region=NL&limit=3' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than your plan's requests per second (10 on Free and Basic, 20 on Pro, 50 on Plus). Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

The Free and Basic plans allow up to 10 requests per second, Pro allows 20 and Plus allows 50. Each plan also has a monthly call quota shown on the pricing page. Going over your plan's per-second limit returns `429 Too Many Requests`. Throttle your client to stay under it, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **Can I search ads shown in the US?**

    TikTok's Ads Library does not accept `region=US`. Use `region=all` to include US ads in the global results.

*   **How do I get the next page?**

    Send the `_next_search_id` and `_next_offset` from the previous response as `search_id` and `offset`, with the same filters.

*   **What does only_total do?**

    It returns just the number of matching ads, with no ad rows.

*   **How many results does the Free plan return?**

    Free plans return at most 10 results per call. Paid plans return the full result set up to the endpoint's limit.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Search the public TikTok Ads Library by keyword, advertiser or ad ID and get ad text, images, videos, run dates and status as JSON.

TikTok Ads Library API: Ad Creatives and Advertisers