# TikTok Ad Library Search API (https://www.socialcrawl.dev/platforms/tiktok/adlibrary-search)

> Returns ads from the TikTok Ad Library (the EU Commercial Content Library) matching a keyword or advertiser name, 12 per page. Each ad carries the creative video, the title, the advertiser name, the impression estimate at `engagement.views`, the spend band, the first-shown date and the audit status. The search row publishes no brand, landing page, advertiser account or avatar, so on a plain call `post.ext.ad.brand_name`, `post.ext.ad.landing_page`, `post.ext.ad.profile_web_link` and `post.author.avatar_url` are null on every row. Send `include=ad` and every row is joined, in the same call, to the per-ad lookup that carries them: the registered brand name, the landing page, the advertiser's TikTok profile link and avatar, and where the library has them the campaign objectives, the countries the ad ran in and the ad source. Cost: 5 credits for the page plus 1 credit per ad filled from a fresh lookup (12 ads, so 17 at most); ads already in cache are filled for free, ads that could not be filled are refunded, and a repeat within the cache window is 0. Time: a plain call is 4 to 19 seconds; `include=ad` adds 5 to 20 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 20 seconds) and nothing when the ads are already cached. `limit=N` (1 to 12) takes the top N ads and, with `include`, caps the extra credits at N. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. Like, comment and share counts are not published by the library on either call. Page with cursor.

TL;DR: `GET /v1/tiktok/adlibrary/search` costs 5 credits for the page. include=ad holds 1 credit per ad, at most 12 (or `limit`), and keeps only the ads filled from a fresh lookup, so a page is at most 17 credits; ads served from cache are free, unfilled ads are refunded, and a repeat within the cache window costs 0. The page is cached for 2 minutes and the per-ad lookups for 30 minutes. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | no | Keyword or phrase to search the TikTok Ad Library. |
| `advertiser_name` | no | Advertiser name as it appears in the TikTok Ad Library. |
| `cursor` | no | Cursor from the previous response to fetch the next page. |
| `include` | no | Set to `ad` (one token only) to fill the registered brand name, the landing page, the advertiser's TikTok profile link and avatar (`post.ext.ad.brand_name`, `post.ext.ad.landing_page`, `post.ext.ad.profile_web_link`, `post.author.avatar_url`), plus the objectives, countries and source where the library has them, on every ad in this one call. Holds 1 credit per ad (at most 12, or `limit`) and keeps only the ads filled from a fresh lookup; ads already in cache and ads that could not be filled are refunded, so the most a call can cost is 5 + ads. Adds 5 to 20 seconds on a fresh page (never more than 20) and nothing when the ads are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. (ad) |
| `limit` | no | Take the top N ads of the page (1 to 12) after the search has run. With `include=ad` it also caps the extra credits at N: `limit=3&include=ad` costs at most 8. It is not a page size: `next_cursor` still advances past the full page. |
| `since` | no | Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. |
| `until` | no | Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. |
| `max_pages` | no | 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. |
| `max_items` | no | 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. |
| `max_credits` | no | 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/tiktok/adlibrary/search" \
  --data-urlencode "advertiser_name=Gymshark" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I search the TikTok Ad Library with an API?

Send a GET request to /v1/tiktok/adlibrary/search with query set to a keyword, or advertiser_name set to the advertiser as it appears in the library. Each page returns the ads that matched with the creative video, the title, the advertiser name, the impression estimate, the spend band, the first-shown date and the audit status. Page with cursor.

### How do I get the brand and landing page for each ad?

Add include=ad and every ad on the page is filled from the per-ad record in the same call: the registered brand name, the landing page, the advertiser's TikTok profile link and avatar, and the objectives, countries and source where the library has them. Ads already in cache are filled for free, ads that could not be filled are refunded and named in _warnings, and the response carries a hydration block with the rows looked up, filled and served from cache and the credits held and kept.

### How much does the TikTok Ad Library search cost?

A plain page costs 5 credits on the advanced tier. With include=ad the call holds one more credit per ad and keeps it only for ads filled from a fresh lookup, so a full page of 12 ads is at most 17 credits; limit caps the ads and the extra credits together. New accounts get 100 free credits with no credit card required.

### Does the TikTok Ad Library return like, comment or share counts?

No. The library publishes an impression estimate and a spend band, not engagement counts, so likes, comments and shares are null on both the search page and the per-ad record. For the performance side of TikTok advertising use /v1/tiktok/ads/top, which reads the Creative Center board.

### How do I page through TikTok Ad Library results?

Read pagination.next_cursor on the response and pass it back as the cursor parameter on the next request; has_more turns false on the last page. include=ad and limit work on every page of the walk. limit takes the top N ads of a page and caps the extra credits with it, and it is not a page size: the cursor still advances past the full page.

See the full TikTok API: https://www.socialcrawl.dev/platforms/tiktok

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to search the TikTok Ad Library with the SocialCrawl API
- What does the SocialCrawl TikTok Ad Library search return?