# TikTok Ads Library Scraper | from $0.50/1K Ads, No Login (`alexmorain/tiktok-ads-library-scraper`) Actor

Scrape the TikTok Commercial Content Library by keyword, advertiser or URL: every ad with call to action, objective, destination URL, targeting and TikTok account. Fixes the library's early end of pagination. No login, no browser per ad.

- **URL**: https://apify.com/alexmorain/tiktok-ads-library-scraper.md
- **Developed by:** [Alexis Morain](https://apify.com/alexmorain) (community)
- **Categories:** Social media, Marketing, Lead generation
- **Features:** Limited permissions
- **Stats:** 4 total users, 4 monthly users, 87.5% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 ads

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

This Actor turns the [TikTok Commercial Content Library](https://library.tiktok.com/ads) (the TikTok Ads Library) into structured data. Type a keyword or a brand, pick a country or none, and it returns every ad the library lists, each with its whole detail page: call to action, advertising objective, destination URL with UTM parameters, targeted audience size, reach by country, age and gender, the targeting the advertiser chose, and the advertiser's TikTok account with its follower count.

It runs over plain HTTP. No TikTok login, no cookies, no browser opened per ad. A headless browser is started once per run, only to make the short-lived access tokens the library asks for, and everything else is HTTP. Pricing is pay per event: $1.00 per 1,000 ads at the entry price (from $0.50 on Gold), $2.00 per 1,000 ads with their detail page (from $1.00 on Gold), and $0.002 per run. A first run capped at 24 ads with full details costs about five cents on the Free plan.

If you were looking for a **TikTok Ads Library API**, this is the closest thing that exists. TikTok publishes a research API for academics but no public API for the ad library. The library is a web page built to satisfy the EU Digital Services Act, and this Actor reads that page the way a browser does, then hands you JSON.

What makes it different from most TikTok ad scrapers is one thing the library does to everyone: its search says it has finished when it has not. A page comes back short, or empty, or with `has_more: false`, while the total it announced is still far away. A scraper that trusts that signal stops early and returns a fraction of the ads without telling you. This Actor replays the missing pages, merges three sort orders, splits big searches by country and by date, and writes what the library announced against what it found in the run log and in a `RUN_SUMMARY` record.

***

### What does this TikTok ads scraper do?

It searches the library in three ways, and the three can be mixed in one run.

Search by keyword. Search terms work like the search box of the library: every ad whose text or advertiser name matches, from any advertiser. Use it to follow a market or a product (`running shoes`), or to find competitors you had not thought to list. Tick Exact phrase to match the words in order instead of in any order.

Search by advertiser. You write the advertiser as the library shows it (`Snipes SE`, `Nike Retail B.V.`). The Actor looks the name up in the library suggestions and follows only an exact match, so it never bills another advertiser's ads by mistake. When nothing matches, the log lists the closest names. Only that advertiser's ads come out, not every ad that mentions the brand.

Replay a library URL. Build a search on library.tiktok.com with filters you like, copy the address and paste it. The keyword or advertiser, the country, the dates and the sort in the URL are kept. A single ad URL (`library.tiktok.com/ads/detail/?ad_id=...`) fetches that one ad.

Two more inputs fetch known ads directly: Ad URLs and Ad IDs, no search, just the detail page of each ad.

On top of any search you get the library filters (country, active or inactive, video or image, targeted age, targeted gender, unique reach band, dates), a Search depth setting, a New ads only mode with a persistent registry for scheduled monitoring, and an optional webhook at the end of the run.

### Why use this TikTok Ads Library scraper?

#### It finds the ads TikTok's own pagination loses

Read a search page after page, 12 ads at a time, and at some point a page comes back with fewer than 12 ads, or none, or says there is nothing more. The announced total is still hundreds or thousands away. Read naively, you stop there.

Measured on 1 November 2026, searches in France or Germany over the last 30 days:

| Search | Announced by the library | Returned by this Actor | Run time |
|---|---|---|---|
| `nike`, France, active ads | 552 | 550 | 58 s |
| `intersport`, Germany | 544 | 539 | 65 s |
| Advertiser `Snipes SE`, France, 21 days | 4,813 | 4,820 | 23 min |
| Advertiser `Snipes SE`, France, 30 days, split in two by the Actor because the total is above 5,000 | 9,649 | 9,468 | 5 min |

The same `nike` search read with plain pagination, without replaying pages and without merging sorts, gave 8 ads out of 543 announced in one test, and 137, 33 and 212 out of 548 in three others. Same library, same query, an unreliable answer every time.

The announced total itself moves between two calls (552, 547 and 541 on the same search), so treat it as a guide and not as a truth. That is why a result can be a little above 100 percent, as on the 21-day Snipes run.

How the repair works, in short: short pages are replayed on a fresh access token and a fresh IP; three sort orders (newest, oldest, most reach) run in parallel and are merged; a search that reports 5,000 or more is split by country, then by date range; the search stops as soon as everything announced has been found. The `RUN_SUMMARY` record in the key-value store tells you, per target, how many ads were announced, found and delivered, how many pages were short, how many were repaired, and how many splits it took.

#### The detail of each ad, without a browser per ad

The list the library shows has a text, a media and a reach band. The interesting part is in the detail page of each ad, and that page is behind a token that allows only a handful of calls. This Actor makes tokens in quantity and rotates them, so a detail costs one HTTP request and not a page load. It reads:

- the call to action button (`Order now`, `Shop now`, `Learn more`) and the advertising objective chosen by the advertiser (`Sales`, `Reach`)
- the destination URL with its UTM parameters, and its domain
- the size of the targeted audience, as a range and as two numbers
- the reach for each country, broken down by age and gender
- the targeted countries, ages and genders, plus cities, provinces, languages, device models, operating systems, interests, video and creator interactions, custom audience, excluded audience and high spending power when the advertiser set them
- the advertiser ID, the payer, the country where the advertiser is registered
- the TikTok account the ad runs from: username, display name, follower count, profile link, account type

#### All the DSA countries in one run

The library covers the European Union, the European Economic Area (Norway, Iceland, Liechtenstein), Switzerland, the United Kingdom and Türkiye: 33 countries. Leave Countries empty and the Actor searches all of them. Choose a list and it searches them one by one, merges the results and returns each ad once.

#### Watch a competitor without paying twice

Switch Mode to New ads only and schedule the run every day. The Actor keeps a registry of the ads previous runs returned and charged, returns only ads it has never returned, and fetches no detail for the old ones. You pay for the new ads only. Add a webhook URL and you are told when a competitor launches something.

#### What the Apify platform adds

Schedules, API and client libraries, webhooks, integrations, exports to JSON, CSV, Excel, XML and HTML, run history and monitoring. Proxies are handled for you.

### What data can the TikTok Ads Library scraper extract?

Every item is one ad. The fields marked "detail" come from the detail page and are filled when Full detail of each ad is on (the default).

| Field | Type | What it holds | Example |
|---|---|---|---|
| `adId` | string | Ad ID in the library | `1876931561471266` |
| `adUrl` | string | Public detail page of the ad | `https://library.tiktok.com/ads/detail/?ad_id=1876931561471266` |
| `advertiserName` | string | Advertiser as the library shows it | `Snipes SE` |
| `advertiserId` | string | Advertiser ID in the library (detail) | `6876496928549372673` |
| `payer` | string | Who paid for the ad (detail) | `SNIPES SE` |
| `advertiserCountry` | string | Country where the advertiser is registered, in the Detail language (detail) | `Germany` |
| `format` | string | `VIDEO` or `IMAGE`, null when the library exposes no media for the ad and no format filter was used | `VIDEO` |
| `body` | string | Ad text | `Discover Nike at SNIPES.` |
| `ctaText` | string | Call to action button (detail) | `Order now` |
| `linkUrl` | string | Destination URL with its UTM parameters (detail) | `https://www.snipes.com/fr-fr/c/sale-660?utm_source=tiktok...` |
| `linkDomain` | string | Domain of the destination (detail) | `snipes.com` |
| `objective` | string | Advertising objective (detail) | `Sales` |
| `category` | string | Industry of the ad as the library classifies it | `Apparel & Accessories` |
| `firstShown` | string | First day the ad was shown, UTC | `2026-09-25T00:00:00Z` |
| `lastShown` | string | Last day the ad was shown, UTC | `2026-10-12T00:00:00Z` |
| `daysRunning` | integer | Days between first and last shown, both counted | `18` |
| `uniqueReach` | string | Estimated unique reach band | `10K-100K` |
| `reachMin` | integer | Lower bound of the reach band | `10000` |
| `reachMax` | integer | Upper bound of the reach band, null for an open band | `100000` |
| `videoUrl` | string | First video of the ad. Signed URL that expires within hours | |
| `coverImageUrl` | string | Cover of the first video. Signed URL | |
| `videos` | array | Every video: `videoUrl` and `coverImageUrl` | |
| `imageUrls` | array | Images of the ad. Signed URLs | |
| `tiktokUsername` | string | TikTok account the ad runs from (detail) | `snipes` |
| `tiktokDisplayName` | string | Display name of that account (detail) | `snipes` |
| `tiktokFollowers` | integer | Followers of that account (detail) | `802400` |
| `tiktokFollowersRaw` | string | Followers as the library writes them (detail) | `802.4K` |
| `tiktokProfileUrl` | string | Profile link of that account (detail) | |
| `tiktokAvatarUrl` | string | Avatar of that account. Signed URL (detail) | |
| `tiktokAccountType` | string | Account type, for example a verified business account (detail) | `BLUEV_BA` |
| `targetAudienceSize` | string | Size of the targeted audience, as a range (detail) | `23.1M-28.2M` |
| `targetAudienceMin` | integer | Lower bound of the targeted audience (detail) | `23100000` |
| `targetAudienceMax` | integer | Upper bound of the targeted audience (detail) | `28200000` |
| `targetCountries` | array | Countries the ad targets (detail) | `["FR"]` |
| `reachByCountry` | array | Reach per country with the age by gender breakdown: `country`, `reach`, `breakdown[{age, gender, reach}]` (detail) | see below |
| `targetAges` | array | Targeted age ranges per country: `country`, `ages` (detail) | `[{"country":"FR","ages":["13-17","18-24"]}]` |
| `targetGenders` | array | Targeted genders per country: `country`, `genders` (detail) | `[{"country":"FR","genders":["female","male"]}]` |
| `cities` | array | Targeted cities (detail) | `[]` |
| `provinces` | array | Targeted provinces or regions (detail) | `[]` |
| `languages` | array | Targeted languages (detail) | `[]` |
| `deviceModels` | array | Targeted device models (detail) | `[]` |
| `operatingSystems` | array | Targeted operating systems (detail) | `["ALL"]` |
| `interests` | string | Targeted interests (detail) | |
| `videoInteractions` | string | Targeting by video interactions (detail) | |
| `creatorInteractions` | string | Targeting by creator interactions (detail) | |
| `customAudience` | boolean | Whether a custom audience is used (detail) | `false` |
| `audienceExclude` | boolean | Whether an audience is excluded (detail) | `true` |
| `highSpendingPower` | boolean | Whether high spending power is targeted (detail) | `false` |
| `auditStatus` | string | Review status of the ad in the library | `1` |
| `rejectionInfo` | object | Why TikTok rejected or removed the ad, when it did: `reasons`, `reporting_source`, `automated_notice` | |
| `hasDetails` | boolean | True when the detail page was fetched, false for a list-only row | `true` |
| `input` | string | The search term, advertiser, URL or ID that produced the row | `Snipes SE` |
| `inputType` | string | `searchTerm`, `advertiser`, `searchUrl` or `adId` | `advertiser` |
| `searchCountries` | array | Countries searched | `["FR"]` |
| `scrapedAt` | string | When the row was collected, UTC | `2026-11-01T05:19:32Z` |

`reachByCountry` holds one entry per country, and in each a breakdown of 18 cells (six age bands times male, female and unknown), each with its own reach band. `targetAudienceSize` is the pool the advertiser aimed at, `uniqueReach` is who the ad reached so far. The library gives reach bands and no spend figure, so there is no spend field.

The TikTok account fields are filled when the ad runs from a TikTok account that the library links to it, typically a business account. Some ads carry none. On the `Snipes SE` advertiser run, 24 ads out of 24 carry one; on a run over every country for `intersport`, 42 out of 100 did; on a `nike` keyword run in France, none of the 60 ads checked did.

The dataset has four ready views in the console: Ads, Targeting, TikTok account and Creatives.

### How to scrape the TikTok Ads Library

#### From the Apify console

1. Open the Actor and go to the Input tab. A search term (`nike`), one country (`FR`) and a cap of 24 ads are already filled in, so pressing Start gives you a real dataset to look at for about five cents.
2. Replace the search term with the keywords you care about, one per line. To follow a brand, use Advertisers instead and write the name as the library shows it. Add Search URLs if you built a search on library.tiktok.com.
3. Choose the countries. Leave the field empty for all 33 countries of the library in one run.
4. Narrow the search if you can. Active or inactive, video or image, targeted age and gender, reach band and dates are all applied by the library itself, so every filter you set makes the run faster and cheaper. With no dates, the Actor reads the 30 days before today.
5. Keep Max ads per target on your first run. A keyword can reach tens of thousands of ads and a big advertiser more, and you pay for each. Set it to 0 once you know what you are getting.
6. Turn Full detail of each ad off if you only need the list (text, media, advertiser, dates, reach band). It halves the price per ad and the run is several times faster.
7. Press Start. When the run finishes, open the Dataset tab and export as JSON, CSV, Excel, XML or HTML, or read it from the API.

#### From the API

Every run is also a REST call. The Actor ID is `alexmorain/tiktok-ads-library-scraper`, and the Python, JavaScript and cURL examples further down are ready to paste. For anything long-running, start the run asynchronously and collect the dataset later, or attach a webhook so Apify calls you when the run succeeds.

### Input

Fill at least one of Search terms, Advertisers, Search URLs, Ad URLs or Ad IDs. The Actor stops with a readable message if all five are empty, rather than running an empty search and charging you for it. A run takes up to 500 targets.

| Input field | What it is for | Example |
|---|---|---|
| `searchTerms` | One search per keyword, as in the library search box. Surfaces advertisers you did not know about. Up to 100 characters each. | `["running shoes", "nike"]` |
| `exactMatch` | Search terms match the exact phrase instead of all the words in any order. | `true` |
| `advertisers` | One search per advertiser, written as the library shows it. Only an exact match is followed, and the log lists the closest names when nothing matches. An advertiser ID alone is refused by the library, so the Actor refuses it too. | `["Snipes SE"]` |
| `searchUrls` | Replays a search copied from `library.tiktok.com/ads?...`. Keyword or advertiser, country, dates and sort in the URL are kept for that URL. | `["https://library.tiktok.com/ads?region=FR&adv_name=nike&query_type=1"]` |
| `adUrls` | Single ads, fetched directly with their detail page. No search. | `["https://library.tiktok.com/ads/detail/?ad_id=1876931561471266"]` |
| `adIds` | The same by ID, a number of 10 to 22 digits. | `["1876931561471266"]` |
| `countries` | Only ads shown in these countries (33 codes: EU, EEA, CH, GB, TR). Empty means all of them in one search. Several countries are searched one by one and each ad comes out once. | `["FR", "DE"]` |
| `startDate` and `endDate` | Only ads shown in this window, `YYYY-MM-DD`. Empty start: 30 days before the end date. Empty end: today. The library refuses a window over 1,200 days and keeps about a year of ads. It is a shown date: an ad that started earlier and still ran on that day is kept, so read `firstShown` for the launch date. | `"2026-10-01"` and `"2026-10-31"` |
| `adStatus` | `all`, `active` (running now) or `inactive` (stopped). | `"active"` |
| `adFormat` | `all`, `video` or `image`. | `"video"` |
| `ages` | Only ads that target these age ranges (`13-17`, `18-24`, `25-34`, `35-44`, `45-54`, `55+`). The library does not combine several, so each range is searched on its own and merged. | `["18-24", "25-34"]` |
| `gender` | `all`, `female` or `male`. | `"female"` |
| `reach` | Only ads whose estimated unique reach is in these bands (`0-10K`, `10K-100K`, `100K+`). Several bands are searched one by one and merged. | `["100K+"]` |
| `sortBy` | Empty for the thorough search. Pick `newest`, `oldest`, `mostReach` or `lastShown` to run that single pass only: faster, but it misses the ads the library loses on that sort. | `"mostReach"` |
| `includeDetails` | On (default): each ad comes with its detail page and is billed as a detailed ad. Off: the list row only, billed as a plain ad. | `true` |
| `detailLanguage` | `en` writes the advertiser's country in English. A full locale such as `fr-FR` or `de-DE` writes it in that language. Two-letter codes other than `en` are ignored by the library. | `"fr-FR"` |
| `maxAdsPerSearch` | Stops each search term, advertiser or URL after this many ads. `0` for no cap. Default 1,000. | `500` |
| `thoroughness` | `complete` (default) repairs the library's lost pages and merges three sorts. `fast` runs one sort with the page replays only. | `"complete"` |
| `maxConcurrency` | How many proxy sessions work at once, 1 to 8, default 4. Each is one IP with its own access tokens. | `4` |
| `mode` | `all` returns every ad found. `new-only` returns only ads no previous run returned. | `"new-only"` |
| `registryKey` | New ads only. Names the memory of already-seen ads. Empty: derived from the targets, countries and filters, so changing any of them starts a fresh one. Dates and the cap are not part of the key. | `"weekly-watch"` |
| `webhookUrl` | Your endpoint, called with a JSON summary at the end of a run that returned at least one ad. Stored as a secret. | `"https://example.com/hooks/tiktok-ads"` |
| `proxyConfiguration` | Leave as is. The library accepts datacenter IPs, and the Actor switches to residential proxies by itself if the library ever refuses them. | `{"useApifyProxy": true}` |

#### Input examples

Ads about a keyword, in two countries, running now:

```json
{
  "searchTerms": ["running shoes"],
  "countries": ["DE", "FR"],
  "adStatus": "active",
  "maxAdsPerSearch": 500
}
```

Everything one advertiser ran in France in October, with full details:

```json
{
  "advertisers": ["Snipes SE"],
  "countries": ["FR"],
  "startDate": "2026-10-01",
  "endDate": "2026-10-31",
  "maxAdsPerSearch": 0
}
```

A search copied from the library website:

```json
{
  "searchUrls": [
    "https://library.tiktok.com/ads?region=FR&start_time=1761955200000&end_time=1762041600000&adv_name=nike&adv_biz_ids=&query_type=1&sort_type=last_shown_date,desc"
  ],
  "maxAdsPerSearch": 200
}
```

A daily competitor watch with a notification, all countries, full details on the new ads only:

```json
{
  "advertisers": ["Snipes SE", "Nike Retail B.V."],
  "mode": "new-only",
  "registryKey": "sneaker-watch",
  "includeDetails": true,
  "webhookUrl": "https://example.com/hooks/tiktok-ads"
}
```

### Monitoring

#### Only new ads, for scheduled monitoring: `"mode": "new-only"`

The library does not sort by launch date, so a run reads the whole search each time. In New ads only mode the Actor keeps a registry of the ads that earlier runs returned and charged, and a new run returns only the others. It fetches no detail for the old ones, so the bill is the new ads only.

The registry belongs to the exact targets, countries and filters. Change the keyword list, the countries or a filter and you start a fresh registry. Dates and the cap are not part of it, which lets you keep the same registry from week to week. If you want to edit the list and keep your history, set `registryKey` yourself.

A run with nothing new ends with the message "No new ads since the last run" and a charge of the start event only.

Schedule it from the Schedules tab of Apify, daily at a fixed hour. Because each run looks at the last 30 days by default, an ad that launched and ended between two runs is still found.

#### Webhook at the end of the run: `webhookUrl`

If you set a URL, the Actor sends a small POST at the end of the run, only when at least one ad was returned:

```json
{
  "actor": "tiktok-ads-library-scraper",
  "runId": "ab12CdEf34GhIj56K",
  "mode": "new-only",
  "items": 7,
  "targets": 2
}
```

Use the final URL: a redirect is not followed, except a 307 or 308, which gets the same POST once. A webhook that cannot be reached is written to the log as a warning and never fails the run. The URL is stored encrypted and appears in no log. The body is a plain summary, not a chat message: a Slack or Discord incoming webhook expects its own format, so point the webhook at an n8n, Make or Zapier scenario and format the message there.

### Example output

An ad from the `Snipes SE` advertiser in France, with its detail page. URLs of signed media are shortened here.

```json
{
  "adId": "1876931561471266",
  "adUrl": "https://library.tiktok.com/ads/detail/?ad_id=1876931561471266",
  "advertiserName": "Snipes SE",
  "advertiserId": "6876496928549372673",
  "payer": "SNIPES SE",
  "advertiserCountry": "Germany",
  "format": null,
  "body": "LES BONS PLANS DE LA SEMAINE. Jusqu’à -50 % + 5 % extra pour les membres SNIPES CLUB. Hors sélection",
  "ctaText": "Order now",
  "linkUrl": "https://www.snipes.com/fr-fr/c/sale-660?utm_source=tiktok&ut...",
  "linkDomain": "snipes.com",
  "objective": "Sales",
  "category": "Apparel & Accessories",
  "firstShown": "2026-09-25T00:00:00Z",
  "lastShown": "2026-10-12T00:00:00Z",
  "daysRunning": 18,
  "uniqueReach": "10K-100K",
  "reachMin": 10000,
  "reachMax": 100000,
  "videoUrl": null,
  "coverImageUrl": null,
  "videos": null,
  "imageUrls": null,
  "tiktokUsername": "snipes",
  "tiktokDisplayName": "snipes",
  "tiktokFollowers": 802400,
  "tiktokFollowersRaw": "802.4K",
  "tiktokProfileUrl": "https://www.tiktok.com/share/user/6678356281658885126?source...",
  "tiktokAvatarUrl": "https://p16-common-sign.tiktokcdn-eu.com/tos-useast2a-avt-00...",
  "tiktokAccountType": "BLUEV_BA",
  "targetAudienceSize": "23.1M-28.2M",
  "targetAudienceMin": 23100000,
  "targetAudienceMax": 28200000,
  "targetCountries": ["FR"],
  "reachByCountry": [
    {
      "country": "FR",
      "reach": "59K",
      "breakdown": [
        { "age": "13-17", "gender": "MALE", "reach": "0-1K" },
        { "age": "13-17", "gender": "FEMALE", "reach": "0-1K" },
        { "age": "13-17", "gender": "UNKNOWN", "reach": "0-1K" }
      ]
    }
  ],
  "targetAges": [{ "country": "FR", "ages": ["13-17", "18-24", "25-34", "35-44", "45-54", "55+"] }],
  "targetGenders": [{ "country": "FR", "genders": ["female", "male", "unknown"] }],
  "cities": [],
  "provinces": [],
  "languages": [],
  "deviceModels": [],
  "operatingSystems": ["ALL"],
  "interests": null,
  "videoInteractions": null,
  "creatorInteractions": null,
  "customAudience": false,
  "audienceExclude": false,
  "highSpendingPower": false,
  "auditStatus": "1",
  "rejectionInfo": null,
  "hasDetails": true,
  "input": "Snipes SE",
  "inputType": "advertiser",
  "searchCountries": ["FR"],
  "scrapedAt": "2026-11-01T05:19:32Z"
}
```

The breakdown is cut to three of its 18 cells. You can download the dataset in various formats such as JSON, HTML, CSV or Excel. A second record, `RUN_SUMMARY`, sits in the key-value store of the run and lists, per target, the ads announced, found and delivered.

#### Ads the library removed

Some ads were taken down by TikTok after review. They stay in the library with `auditStatus` set to `2`, an empty advertiser name and a `rejectionInfo` object with the reasons. Their detail page is complete for everything else (objective, targeting, reach), so they come out with `hasDetails: true` and a null `advertiserName`.

### Using the TikTok Ads Library API from your code

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("alexmorain/tiktok-ads-library-scraper").call(run_input={
    "advertisers": ["Snipes SE"],
    "countries": ["FR"],
    "adStatus": "active",
    "maxAdsPerSearch": 200,
})

for ad in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(ad["advertiserName"], ad["ctaText"], ad["objective"], ad["targetAudienceSize"], ad["linkUrl"])

```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('alexmorain/tiktok-ads-library-scraper').call({
    searchTerms: ['running shoes'],
    countries: ['DE', 'FR'],
    adStatus: 'active',
    maxAdsPerSearch: 500,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const ad of items) {
    console.log(ad.advertiserName, ad.objective, ad.uniqueReach, ad.linkDomain);
}
```

#### cURL

Start a run and get the run object back at once:

```bash
curl -X POST "https://api.apify.com/v2/acts/alexmorain~tiktok-ads-library-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"advertisers": ["Snipes SE"], "countries": ["FR"], "maxAdsPerSearch": 200}'
```

### What people use it for

- Competitor ad analysis: list a competitor under Advertisers and read the creatives, the offer in the destination URL, the objective, the call to action and how long each ad has run. An ad that has run 60 days either works or nobody checked it. Sort by `daysRunning` and `uniqueReach` for the short list.
- Reading targeting choices: audience size, countries, ages, genders, interests, devices, custom and excluded audiences. Compare two competitors and see whether they chase the same people.
- Reach by country, age and gender: aggregate it across a brand's ads to see who they actually reached, which is not always who they aimed at.
- Market entry detection: run New ads only on a list of competitors across all countries and let the webhook tell you when a first ad shows up somewhere new.
- Creative research: search a category, sort by most reach, read the top creatives and their calls to action. Video URLs expire within hours, so download what you keep right away.
- Landing page and UTM audit: group by `linkDomain` and read the `utm_campaign` values to see how a competitor structures its campaigns.
- Brand protection and research: the library also lists ads TikTok removed after review, with the reasons.
- Lead lists: a keyword search over a category, grouped by advertiser, gives the companies that spend on TikTok there, with their registered country, payer and account.

### Pricing

The Actor uses pay per event. You pay for three things and nothing else. The platform usage of the run is included.

| Event | Free | Bronze | Silver | Gold and above |
|---|---|---|---|---|
| Actor Start, per run and per GB of memory (1 GB by default) | $0.002 | $0.002 | $0.002 | $0.002 |
| Ad, per 1,000 ads without detail | $1.00 | $0.90 | $0.70 | $0.50 |
| Detailed ad, per 1,000 ads with their detail page | $2.00 | $1.70 | $1.50 | $1.00 |

Platinum and Diamond are priced as Gold.

What this means in practice, on the Free plan:

| Job | Ads | Cost |
|---|---|---|
| Default first run: 24 ads with details | 24 | about $0.05 |
| 550 ads for a brand in one country, list only | 550 | about $0.55 |
| The same 550 ads with details | 550 | about $1.10 |
| 1,000 ads with details | 1,000 | $2.00 plus $0.002 |
| 10,000 ads with details | 10,000 | $20.00 (a Gold plan pays $10.00) |

Three rules about what is billed:

- An ad whose detail page the library refuses to give comes out with `hasDetails: false` and is billed as a plain ad, not as a detailed one.
- An ad is never billed twice. In a run each ad comes out once, even when several countries or several searches find it. In New ads only mode an ad returned by an earlier run is not returned again and not billed again.
- A run that finds nothing is billed the start event only. If you set a maximum cost per run, the Actor stops cleanly when it reaches it and tells you in the run status.

How long it takes, measured on the platform with 1 GB of memory and 4 parallel sessions: 1,000 ads without detail in about two minutes, 1,000 ads with detail in about twelve. The detail is the slow part, around 1.4 ads per second per run. If you only need the text, the dates and the reach band, switch the detail off.

### Limits and what this scraper does not do

It reads the TikTok Commercial Content Library, and that library has its own boundaries.

- Coverage is the Digital Services Act countries: the European Union, Norway, Iceland, Liechtenstein, Switzerland, the United Kingdom and Türkiye. There are no ads for the United States or any country outside that list.
- The library keeps about a year of ads and refuses a date range over 1,200 days.
- There is no spend figure and no exact impression count. The library publishes a unique reach band per ad and per country, and this Actor gives you those bands.
- Video and image URLs are signed and expire within hours. Download the files you need during the run or right after it.
- Many image ads are listed without an image URL, so `format` is null for them unless you use the format filter.
- The total the library announces is not stable. It moves by up to about 10 percent between two calls, and it is capped at 5,000 on display. The Actor splits above that and reports what it found against what was announced, but it cannot promise the exact number the library will show you tomorrow. The runs above found between 98.1 and 100.1 percent of the announced totals.
- The TikTok account fields exist only for ads where the library links a TikTok account to the ad. Many ads carry none.
- A very large advertiser with tens of thousands of ads and detail on takes hours. The default run timeout is one hour: raise it for big jobs, or the Actor stops cleanly before the timeout and tells you how many ads it returned.
- An advertiser is searched by its exact name. The library does not accept an advertiser ID alone, and its name suggestions sometimes come back empty, so the Actor asks again several times before it says the advertiser was not found.
- Ads removed by TikTok have no advertiser name. See Ads the library removed above.
- It does not log in, and it does not download the videos for you.

### FAQ

#### How to scrape the TikTok Ads Library?

Open the Actor, type a keyword or an advertiser, choose a country, and press Start. The dataset gives you one row per ad. You can also call the Actor from the API, a schedule or an automation tool. There is no login and no browser to set up.

#### Is there a TikTok Ad Library API?

TikTok has no public API for its ad library. There is a research API for approved academics, and the library website. This Actor reads the website and returns JSON, and you call it through the Apify API.

#### How to get TikTok ads targeting data?

Keep Full detail of each ad on. Each ad then carries the audience size, the targeted countries, ages and genders, the reach per country, age and gender, and the interests, languages, devices and custom audience settings when the advertiser used them.

#### How to download TikTok ads by advertiser?

Put the advertiser name in Advertisers, exactly as the library shows it (`Snipes SE`). Choose countries and dates, set Max ads per target to 0 for everything, and start the run. If the name matches nothing, the log lists the closest names.

#### How do I export TikTok ads from the library to CSV or Excel?

Open the Dataset tab of the run, choose Export, and pick CSV or Excel. From the API, add `format=csv` or `format=xlsx` to the dataset items URL. Nested fields (reach by country, targeted ages) are flattened by the export, and the JSON keeps them as they are.

#### Which countries does the TikTok Ads Library cover?

The 27 countries of the European Union, plus Norway, Iceland, Liechtenstein, Switzerland, the United Kingdom and Türkiye. That makes 33 country codes in the input. Ads shown only in the United States or elsewhere are not in the library.

#### How far back does the TikTok Ad Library go?

About one year. A date range of more than 1,200 days is refused by the library, and the Actor tells you before it searches.

#### Why does the TikTok Ad Library show fewer ads than expected, or stop loading?

Its search sometimes says the list has ended while the total it displays is far higher, and the displayed total is capped at 5,000. That is the page loss described above. This Actor replays and merges to reach the announced total, and gives you the announced and found figures per target in `RUN_SUMMARY`.

#### Does the scraper give TikTok ad spend or impressions?

No. The library publishes an estimated unique reach band per ad (for example `10K-100K`) and per country, with an age and gender breakdown. There is no spend figure for commercial ads. If you need spend, use reach and the audience size as a proxy.

#### How do I find all the ads a brand runs on TikTok?

Use the advertiser name. A brand can run its ads from several advertiser accounts, for example `Nike Retail B.V.` or a local entity, so also run a keyword search on the brand and look at the `advertiserName` and `payer` columns to find the other accounts.

#### How do I monitor a competitor's new TikTok ads?

Use New ads only mode on a daily schedule and add a webhook. The run returns only the ads it has not returned before and you pay only for those.

#### How much does it cost to scrape 1,000 TikTok ads?

$1.00 for the list, $2.00 with the detail page, on the Free plan. $0.50 and $1.00 on a Gold plan. Plus $0.002 per run.

#### Is scraping the TikTok Ads Library legal?

The library is a public transparency register published to meet a legal duty, and this Actor reads only what any visitor sees. Ads carry business information, not private user data. Check the use you make of the data, and the rules of your country, if you are unsure.

#### My run returned fewer ads than the library announces. What now?

Check `RUN_SUMMARY` in the key-value store: it shows announced and found per target. A gap of a few percent is the library's own instability. A bigger gap with a status message about a refusal or a timeout means the run was cut: lower `maxConcurrency`, raise the run timeout, or split the search by date range or by country.

#### The advertiser was not found. What now?

Write the name exactly as the library shows it, or paste the URL of the advertiser's search from library.tiktok.com into Search URLs. The library suggestions answer empty at random, so a second run sometimes finds what the first did not.

### Related Actors

The same author publishes three other ad library scrapers, built on the same principle (the real public source, plain HTTP, complete pagination, new-ads-only monitoring):

- [LinkedIn Ad Library Scraper](https://apify.com/alexmorain/linkedin-ad-library-scraper)
- [Facebook Ads Library Scraper](https://apify.com/alexmorain/facebook-ads-library-scraper) for Facebook and Instagram ads
- [Google Ads Transparency Scraper](https://apify.com/alexmorain/google-ads-transparency-scraper)

Together they cover a competitor's ads across TikTok, Meta, LinkedIn and Google.

### Integrations and exports

Results export as JSON, CSV, Excel, XML and HTML. The Actor works with Make, Zapier, n8n, Google Sheets, Slack and Airbyte, with any HTTP client through the API, and with AI agents through the Apify MCP server.

### Support and disclaimer

Something wrong or missing? Open an issue on the Issues tab of the Actor and it gets fixed. If it saved you time, a short review helps others find it. Programmatic access is documented in the API tab.

Our Actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our Actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

This Actor is not affiliated with, endorsed by or sponsored by TikTok or ByteDance. TikTok is a trademark of its owner.

### Guide and use cases

Use cases for outbound and automation, the output fields, pricing and common questions are on the [TikTok Ads Library Scraper page](https://alexis.morain.fr/en/scrapers/tiktok-ads-library-scraper/) of my site. The [Ad libraries family page](https://alexis.morain.fr/en/scrapers/families/ad-library/) puts it side by side with the other scrapers of the same family.

# Actor input Schema

## `searchTerms` (type: `array`):

Keyword searches, as in the library search box: every ad whose text or advertiser name matches, from any advertiser. One term per line.

## `exactMatch` (type: `boolean`):

Search terms match the exact phrase instead of all the words in any order. <code>just do it</code> as a phrase finds that slogan, not every ad with those three words.

## `advertisers` (type: `array`):

Brands whose ads you want, one per line, written as the library shows them (<code>Snipes SE</code>, <code>Nike Retail B.V.</code>). A name is looked up in the library suggestions and <b>only an exact match (case ignored)</b> is followed: the Actor never bills another advertiser's ads. When nothing matches, the log lists the closest names. Only that advertiser's ads come out, not every ad that mentions the brand. Advertisers can have tens of thousands of ads: set Max ads per target.

## `searchUrls` (type: `array`):

Pages copied from <code>library.tiktok.com/ads?...</code>: the keyword or advertiser, the country (<code>region</code>), the dates (<code>start_time</code>, <code>end_time</code>) and the sort in the URL are kept for that URL. One URL per line.

## `adUrls` (type: `array`):

Single ads, <code>https://library.tiktok.com/ads/detail/?ad_id=...</code>. No search: only the detail page of each ad.

## `adIds` (type: `array`):

Single ads by ID (a number of 10 to 22 digits), one per line. Same as Ad URLs.

## `countries` (type: `array`):

Only ads shown in these countries. Leave empty for all the countries of the library in one search. Several countries are searched one by one and each ad comes out once.

## `startDate` (type: `string`):

Only ads shown on or after this date. Empty: 30 days before the end date. The library keeps about a year of ads and refuses a range over 1200 days. Careful: it is a <b>shown</b> date, an ad that started earlier and still ran on this day is kept: read <code>firstShown</code> for the launch date.

## `endDate` (type: `string`):

Only ads shown on or before this date. Empty: today.

## `adStatus` (type: `string`):

Active ads are the ones running now, inactive ads have stopped.

## `adFormat` (type: `string`):

Only video ads, or only image ads. The library often lists an image ad without its image URL, so <code>format</code> is read from the filter you pick when the ad exposes no media.

## `ages` (type: `array`):

Only ads that target this age range. Several ranges are searched one by one and merged, since the library does not combine them. Leave empty for all.

## `gender` (type: `string`):

Only ads that target women or men.

## `reach` (type: `array`):

Only ads whose estimated unique reach is in this band. Several bands are searched one by one and merged. Leave empty for all.

## `sortBy` (type: `string`):

Leave empty for the thorough search (see below). Pick a sort to run that single pass only: faster and cheaper to read, but it misses the ads the library loses on that sort.

## `includeDetails` (type: `boolean`):

On: each ad comes with its detail page (call to action, objective, destination URL, audience size, reach by country, age and gender, targeting, TikTok account) and is billed as an ad with details. Off: the list row only (text, media, advertiser, dates, reach band), billed as a plain ad. A detail the library refuses to give is not billed as a detail: the row comes out with <code>hasDetails: false</code>.

## `detailLanguage` (type: `string`):

<code>en</code> writes the advertiser's country in English. A full locale such as <code>fr-FR</code> or <code>de-DE</code> writes it in that language; two-letter codes other than <code>en</code> are ignored by the library.

## `maxAdsPerSearch` (type: `integer`):

Stop each search term, advertiser or URL after this many ads. <code>0</code> for no cap: a keyword can reach tens of thousands of ads, a big advertiser more, and each is billed.

## `thoroughness` (type: `string`):

<b>Complete</b> (default): the library's search drops pages and says the list ended early; the Actor replays them and merges three sorts, so you get nearly all the ads the library announces (it reports announced against found in the run log and in <code>RUN_SUMMARY</code>). <b>Fast</b>: one sort, with the page replays only.

## `maxConcurrency` (type: `integer`):

How many proxy sessions work at once. Each is one IP with its own access tokens.

## `mode` (type: `string`):

<b>All ads</b> returns every ad the search finds, on every run.<br><br><b>New ads only</b> keeps a persistent registry of the ads previous runs returned and charged, and returns only ads never returned before: schedule it daily to be told when a competitor launches something new. Every run reads the whole search, since the library does not sort by launch date; you pay only for the new ads, and no detail is fetched for the old ones.

## `registryKey` (type: `string`):

By default the registry is tied to the exact targets, countries and filters, so changing any of them starts a fresh one. Set your own key to keep one registry while you edit the list.

## `webhookUrl` (type: `string`):

If set, the Actor POSTs a small JSON summary to this URL at the end of the run, <b>only when at least one ad was returned</b>: <code>actor</code>, <code>runId</code>, <code>mode</code>, <code>items</code>, <code>targets</code>. With New ads only and a daily schedule, that is a push notification when a competitor launches ads.<br><br>Use the final URL: a redirect is not followed, except a 307 or 308, which gets the same POST once. An unreachable webhook is logged as a warning and never fails the run. Stored encrypted.

## `proxyConfiguration` (type: `object`):

Leave as is. The library accepts datacenter IPs. With the plain Apify proxy the Actor switches to residential by itself if the library ever refuses them. A browser makes the access tokens; everything else is plain HTTP.

## Actor input object example

```json
{
  "searchTerms": [
    "nike"
  ],
  "exactMatch": false,
  "countries": [
    "FR"
  ],
  "adStatus": "all",
  "adFormat": "all",
  "gender": "all",
  "includeDetails": true,
  "detailLanguage": "en",
  "maxAdsPerSearch": 24,
  "thoroughness": "complete",
  "maxConcurrency": 4,
  "mode": "all",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

All ads in the default dataset.

## `summary` (type: `string`):

Announced against found, per target: the proof of the search repair.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "nike"
    ],
    "countries": [
        "FR"
    ],
    "maxAdsPerSearch": 24,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("alexmorain/tiktok-ads-library-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": ["nike"],
    "countries": ["FR"],
    "maxAdsPerSearch": 24,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("alexmorain/tiktok-ads-library-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchTerms": [
    "nike"
  ],
  "countries": [
    "FR"
  ],
  "maxAdsPerSearch": 24,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call alexmorain/tiktok-ads-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,alexmorain/tiktok-ads-library-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/22dDFoWsLwgcSBoTV/builds/tYC64shTmL0RKfWqX/openapi.json
