# TikTok Ads Library Scraper – EU/UK Ads, Targeting & Reach (`ferncrawl/tiktok-ads-library-scraper`) Actor

Scrape the official TikTok Ads Library (EU/EEA, UK, CH, TR): ad text, video/image URLs, advertiser, first/last shown, reach, impressions by country/age/gender, targeting. Search by keyword or advertiser. Optional Creative Center top ads.

- **URL**: https://apify.com/ferncrawl/tiktok-ads-library-scraper.md
- **Developed by:** [Fern Crawl](https://apify.com/ferncrawl) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 ad scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## TikTok Ads Library Scraper – EU/UK Ads, Targeting & Reach

Extract ads from the official **[TikTok Ads Library](https://library.tiktok.com/ads)** (TikTok's commercial content repository for the EU/EEA, United Kingdom, Switzerland and Türkiye): ad text, video and image URLs, advertiser, first/last shown dates, unique-user reach, **impressions by country, age and gender**, and the **targeting** TikTok discloses (age, gender, location, interests, audience size, custom audiences).

Search by **keyword** or by **advertiser** (name or ID), pick countries and a date range, and get clean JSON / CSV / Excel.
Optionally add **TikTok Creative Center Top Ads** (worldwide best-performing ads with CTR and likes).

### What you can use it for

- **Competitor research** – see every ad a brand ran in Europe, which creatives it is using now, and how long each one ran.
- **Creative inspiration** – collect top-performing TikTok video ads in your niche, with landing pages and CTAs.
- **Targeting intelligence** – learn which age groups, genders, countries and interests competitors target, and how many impressions each country received.
- **Monitoring & compliance** – schedule daily runs to track new ads from advertisers or keywords.

### Input

| Field | Description |
|---|---|
| `searchTerms` | Keywords, e.g. `nike`, `protein powder`. Each term is a separate search. With a completely empty input the actor runs a small demo search (`nike`, 20 ads). |
| `advertiserNames` | Advertiser legal names, e.g. `Adidas AG` (exact match preferred, otherwise up to 3 containing the name). |
| `advertiserIds` | TikTok business IDs (the `advertiserId` from earlier results) – most precise. |
| `regions` | `all` (default) or any of AT, BE, BG, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, TR. |
| `lastNDays` / `dateFrom` / `dateTo` | Date range of when ads were shown (default: last 30 days). |
| `maxAds` | Maximum ads **per search term / advertiser** (default 20). |
| `fetchDetails` | Adds landing page, CTA, objective, TikTok account, impressions breakdown and targeting (default on). |
| `daySlicing` | Deep search: TikTok only lets you page ~100 results deep per search, so for large `maxAds` the actor also searches day by day (default on). |
| `includeCreativeCenter` | Add-on: Creative Center Top Ads for `ccCountries` (default off). |

Example:

```json
{
  "searchTerms": ["nike"],
  "advertiserNames": ["Adidas AG"],
  "regions": ["DE", "FR", "GB"],
  "lastNDays": 30,
  "maxAds": 100,
  "fetchDetails": true
}
```

### Output

One dataset item per ad. Field names match our **Google Ads Transparency Scraper**, so you can merge both datasets.

```json
{
  "source": "tiktok-ads-library",
  "adId": "1880398616261842",
  "advertiserName": "Example Brand GmbH",
  "advertiserId": "7560696377014026257",
  "format": "VIDEO",
  "adText": "New season drop – shop now #sneakers",
  "firstShown": "2026-10-20T00:00:00Z",
  "lastShown": "2026-10-29T00:00:00Z",
  "daysShown": 10,
  "estimatedAudience": "10K-100K",
  "regions": ["DE", "AT"],
  "previewUrl": "https://library.tiktok.com/ads/detail/?ad_id=1880398616261842",
  "videoUrls": ["https://library.tiktok.com/api/v1/cdn/..."],
  "videoCoverUrls": ["https://p16-common-sign.tiktokcdn.com/..."],
  "imageUrls": [],
  "searchQuery": "sneakers",
  "landingPageUrl": "https://example.com/...",
  "callToAction": "Shop now",
  "objective": "Traffic",
  "impressions": "100K-1M",
  "regionImpressions": [{"region": "DE", "impressions": "100K-1M", "breakdowns": [{"age": "18-24", "gender": "FEMALE", "impressions": "10K-100K"}]}],
  "targetAudienceSize": "20.5M-25.1M",
  "targetingAges": {"DE": ["18-24", "25-34"]},
  "targetingGenders": {"DE": ["female", "male"]},
  "targetingCountries": ["DE", "AT"],
  "customAudience": false,
  "tiktokUsername": "examplebrand"
}
```

(Values above are illustrative.) A run summary (ads per search, resolved advertisers, warnings, HTTP stats) is saved as the `OUTPUT` record of the key-value store.

Creative Center items have `"source": "tiktok-creative-center"` and add `ctr`, `likes`, `comments`, `shares`, `industry`, `ccCountry`, `ccOrderBy`.

### Pricing

Pay per result: you are charged per ad returned (see the Pricing tab). No proxy or subscription needed – the actor works without a proxy, and Apify datacenter proxy also works.

### Performance

- \~20 ads with full details in about 1–2 minutes; without details ~10x faster per ad.
- Runs fine with 512 MB memory. Use 1024 MB when the Creative Center add-on is enabled (it opens a headless browser once).

### Limitations – please read

- **Coverage**: the TikTok Ads Library only contains ads shown in the **EU/EEA, UK, Switzerland and Türkiye**. US-only ads are not there (use the Creative Center add-on for worldwide top ads).
- **Data delay**: TikTok's Library typically lags ~2 days; the last 1–2 days may look empty.
- **Ranges, not exact numbers**: reach and impressions are published by TikTok as ranges (e.g. `10K-100K`).
- **Media URLs expire**: video/image URLs are signed and expire after some time – download them soon if you need the files.
- **Creative Center without login** shows only the first page (~20 ads) per country and sort order; the actor combines 4 sort orders.
- If a search returns 0 ads the run is marked **failed** with a hint (check spelling, widen dates/regions), so monitoring setups notice.
- This actor reads publicly available transparency data. It does not log in or access private information. You are responsible for using the data in line with applicable law and TikTok's terms.

### FAQ

**Why do I get fewer ads than the total shown on library.tiktok.com?** TikTok caps how deep you can page. Keep *Deep search (day slicing)* on and use a longer date range or more specific regions.

**Can I track an advertiser over time?** Yes – run with `advertiserIds` on a schedule; each ad has a stable `adId` for de-duplication.

**Issues or feature requests?** Open an issue on the Issues tab and we will take a look.

# Actor input Schema

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

Keywords searched in ad text and advertiser names (like the search box on library.tiktok.com). Each term is a separate search; maxAds applies per term. If nothing at all is entered (no terms, advertisers or IDs), 'nike' is used as a demo search.

## `advertiserNames` (type: `array`):

Advertiser (legal entity) names, e.g. 'Adidas AG'. Resolved with TikTok's advertiser search; an exact (case-insensitive) match is used if available, otherwise up to 3 advertisers containing the name. Matches are listed in the OUTPUT summary.

## `advertiserIds` (type: `array`):

TikTok business IDs (the 'advertiserId' field of earlier results). Most precise way to track an advertiser.

## `exactPhrase` (type: `boolean`):

Wrap search terms in quotes so the Library matches the exact phrase.

## `regions` (type: `array`):

Countries where the ad was shown. The TikTok Ads Library only covers the EU/EEA, United Kingdom, Switzerland and Türkiye. 'all' = all of them in one search.

## `lastNDays` (type: `integer`):

Ads shown in the last N days (ignored when 'Date from' is set). Note: the Library typically lags ~2 days.

## `dateFrom` (type: `string`):

Optional start date (YYYY-MM-DD).

## `dateTo` (type: `string`):

Optional end date (YYYY-MM-DD), default today.

## `maxAds` (type: `integer`):

Maximum ads per search term / advertiser. You pay per ad returned.

## `fetchDetails` (type: `boolean`):

Adds landing page, CTA, objective, TikTok account, impressions by country/age/gender and targeting (age, gender, location, interests, audience size). Roughly 3x slower; turn off for a quick list.

## `daySlicing` (type: `boolean`):

TikTok only lets you page ~100 results deep per search. When more ads are wanted, the actor also searches day by day to reach older/less popular ads.

## `advertiserMatch` (type: `string`):

How advertiser names are resolved.

## `includeCreativeCenter` (type: `boolean`):

Also collect TikTok Creative Center 'Top Ads' (best-performing ads with CTR, likes, video) for the countries below. Works worldwide (not only EU). Starts a headless browser once — use 1024 MB memory. Charged as a separate event.

## `ccCountries` (type: `array`):

Two-letter country codes, e.g. US, GB, DE, JP.

## `ccPeriodDays` (type: `string`):

Ranking period.

## `ccMaxAds` (type: `integer`):

Total cap. Without login TikTok shows ~20 ads per country and sort order (4 sort orders are combined).

## `ccFetchDetails` (type: `boolean`):

Adds landing page, comments, shares and countries.

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

Optional. Works without a proxy; Apify datacenter proxy also works. Residential proxy is not needed.

## `minRequestIntervalSecs` (type: `number`):

Politeness delay between requests to TikTok.

## Actor input object example

```json
{
  "searchTerms": [
    "nike"
  ],
  "exactPhrase": false,
  "regions": [
    "all"
  ],
  "lastNDays": 30,
  "maxAds": 20,
  "fetchDetails": true,
  "daySlicing": true,
  "advertiserMatch": "exact",
  "includeCreativeCenter": false,
  "ccCountries": [
    "US"
  ],
  "ccPeriodDays": "30",
  "ccMaxAds": 20,
  "ccFetchDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "minRequestIntervalSecs": 1
}
```

# Actor output Schema

## `ads` (type: `string`):

One item per ad: advertiser, ad text, format, video/image URLs, first/last shown, regions, impressions and targeting (with details), plus Creative Center top ads if enabled.

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

JSON summary: resolved advertisers, ads per search, pages, warnings, HTTP stats, errors such as SCHEMA_DRIFT.

# 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"
    ],
    "regions": [
        "all"
    ],
    "maxAds": 20,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("ferncrawl/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"],
    "regions": ["all"],
    "maxAds": 20,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("ferncrawl/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"
  ],
  "regions": [
    "all"
  ],
  "maxAds": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call ferncrawl/tiktok-ads-library-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ferncrawl/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/klNcdN3ETc4MF0ZXC/builds/KAi0cnb0AY0XtdnlI/openapi.json