# TikTok Ads Library Scraper (Commercial Content API) (`bovi/tiktok-ads-library-scraper`) Actor

Scrape TikTok's Commercial Content Library via the official open.tiktokapis.com API. Search ads by keyword or advertiser business ID across EU/EEA/UK regions. Returns creatives, video URLs, reach buckets, targeting, and advertiser metadata. Official API = never breaks on DOM changes.

- **URL**: https://apify.com/bovi/tiktok-ads-library-scraper.md
- **Developed by:** [Vitalii Bondarev](https://apify.com/bovi) (community)
- **Categories:** Social media, Marketing
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.85 / 1,000 listings

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## TikTok Ads Library Scraper — Commercial Content API

Scrape TikTok's **Commercial Content Library** via the official `open.tiktokapis.com` API. Search ads by keyword or advertiser business ID across EU/EEA/UK regions. Returns creatives, video URLs, reach estimates, targeting data, and advertiser metadata — all via the official API, which never breaks on DOM changes.

### Why this actor over alternatives?

| Feature | This actor | Typical DOM scrapers |
|---|---|---|
| **Official API** | Yes — `open.tiktokapis.com` | No — scrapes library.tiktok.com HTML |
| **Stability** | Never breaks on UI changes | Breaks when TikTok redesigns UI |
| **parse\_confidence** | Yes — per-record data quality score | No |
| **Targeting data** | Yes — age/gender/location/interests | Rarely |
| **Per-country reach** | Yes (via `includeDetails`) | No |
| **Proxy needed** | No — official API | Usually yes ($$$) |

### Input

| Field | Required | Description |
|---|---|---|
| `accessToken` | **Yes** | TikTok client access token (`clt.xxx`). Get via research program. |
| `keywords` | One of these | Keywords to search ad copy for. Each runs as a separate query. |
| `advertiserBusinessIds` | One of these | Numeric advertiser business IDs to look up directly. |
| `countryCode` | No | Two-letter country code or `ALL`. EU/EEA/UK only. Default: `ALL`. |
| `dateFrom` | No | Start date, format `YYYYMMDD`. Minimum: `20221001`. |
| `dateTo` | No | End date, format `YYYYMMDD`. Default: today. |
| `searchType` | No | `exact_phrase` (default) or `fuzzy_phrase`. |
| `maxItems` | No | Cap results per keyword. Leave blank = unlimited. |
| `includeDetails` | No | Fetch full targeting + per-country reach (doubles requests). |

### Output schema

Each result row is a flat JSON object:

```json
{
  "ad_id": "1923845247192304",
  "advertiser_name": "Nike EU",
  "advertiser_id": "3847236290405",
  "advertiser_paid_by": "Nike, Inc.",
  "region": "FR",
  "first_shown": "2024-01-01",
  "last_shown": "2024-12-31",
  "status": "active",
  "impressions_range": "11K",
  "video_url": "https://cdn.tiktokcdn.com/video123.mp4",
  "image_urls": [],
  "caption": null,
  "ad_url": "https://library.tiktok.com/ads?adId=1923845247192304",
  "query": "nike",
  "parse_confidence": 1.0,
  "warnings": []
}
```

#### With `includeDetails: true`, additional fields:

```json
{
  "targeting_countries": ["FR", "DE"],
  "targeting_age": {"18-24": true, "25-34": true},
  "targeting_gender": {"female": true, "male": true},
  "targeting_audience_size": "50K",
  "targeting_interests": "Sports, Fitness",
  "reach_by_country": {"FR": "8K", "DE": "3K"},
  "advertiser_profile_url": "https://www.tiktok.com/@nike",
  "advertiser_avatar_url": "https://p16.tiktokcdn.com/avatar.jpeg",
  "advertiser_follower_count": 1200000
}
```

### Supported regions

**EU/EEA/UK only** — TikTok's Commercial Content API covers: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Norway, Iceland, Liechtenstein, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, United Kingdom, Switzerland.

Use `countryCode: "ALL"` to search across all supported regions simultaneously.

### Getting an access token

TikTok's Commercial Content API requires an approved research account:

1. Apply at [developers.tiktok.com](https://developers.tiktok.com) → Research API
2. Once approved, get your `client_key` and `client_secret`
3. Exchange for an access token:

```bash
curl -X POST https://open.tiktokapis.com/v2/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_key=YOUR_KEY&client_secret=YOUR_SECRET&grant_type=client_credentials"
```

The response contains an `access_token` (prefixed `clt.`) — pass this as `accessToken` input.

### FAQ

**Why EU/EEA/UK only?**
TikTok's Commercial Content Library is a transparency measure under the EU Digital Services Act (DSA). Coverage is limited to these jurisdictions by TikTok's API design.

**What is `parse_confidence`?**
A score from 0.0 to 1.0 indicating data quality for each record. 1.0 = all expected fields present. Below 0.5 = critical fields missing — check `warnings` for which ones.

**What does `impressions_range` mean?**
TikTok returns audience reach as bucketed ranges (e.g., "11K", "100K–200K") rather than exact counts, by design. This is the raw value from the API.

**Can I get ad creative text / copy?**
The TikTok Commercial Content API does not expose ad body copy directly. The `caption` field is extracted from rejection reason text when present. For creative copy, use TikTok's Creative Center separately.

**Data since when?**
TikTok's Commercial Content Library covers ads from October 1, 2022 onward.

***

*Not affiliated with TikTok, ByteDance, or their subsidiaries. All data is retrieved from TikTok's public official API.*

### Integrations

Built for ad-intelligence researchers and compliance teams with TikTok API access auditing EU/EEA ad creatives and targeting — the JSON/dataset output drops into the tools you already run, no glue code:

- **n8n / Make / Zapier** — trigger a run or pipe every new dataset item into 500+ apps (Google Sheets, Airtable, Slack, HubSpot, your database) with no code: [n8n](https://docs.apify.com/platform/integrations/n8n), [Make](https://docs.apify.com/platform/integrations/make), [Zapier](https://docs.apify.com/platform/integrations/zapier).
- **Webhooks** — fire your own endpoint the moment a run finishes, to push results straight into your pipeline ([docs](https://docs.apify.com/platform/integrations/webhooks)).
- **MCP server** — expose this actor as a tool to Claude, Cursor, or any [MCP client](https://mcp.apify.com) so an AI agent can pull this data mid-conversation ([guide](https://blog.apify.com/how-to-use-mcp/)).
- **API & SDKs** — fetch the dataset as JSON, CSV, or Excel through the Apify REST API or the Python / JS SDKs.

See all [Apify integrations](https://apify.com/integrations).

# Actor input Schema

## `accessToken` (type: `string`):

Client access token from TikTok's Commercial Content API (open.tiktokapis.com). Obtain via the /v2/oauth/token/ endpoint using your approved research client credentials. Required.

## `keywords` (type: `array`):

Keywords to search ad copy for. Each keyword runs as a separate query. Either this or 'advertiserBusinessIds' is required.

## `advertiserBusinessIds` (type: `array`):

TikTok advertiser business IDs to look up directly. Numeric string IDs. Used instead of keywords when provided.

## `countryCode` (type: `string`):

Two-letter ISO country code for the region filter. TikTok's Commercial Content API covers EU/EEA/UK only. Use 'ALL' to search across all supported regions. See README for supported country list.

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

Start of the ad published date range. Must be on or after 2022-10-01 (API minimum). Format: YYYYMMDD.

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

End of the ad published date range. Format: YYYYMMDD.

## `searchType` (type: `string`):

How to match the keyword: exact\_phrase (default, strict) or fuzzy\_phrase (any/all words in any order).

## `maxItems` (type: `integer`):

Cap results per keyword search. Leave blank for unlimited (follows cursor pagination). Capped at 50 per API page.

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

If enabled, fetches full ad details (age/gender/country targeting, per-country reach, advertiser avatar/follower count) for each ad via a second API call. Doubles request count.

## `sectionCaption` (type: `string`):

Options below are for power users and pagination control.

## `apiVersion` (type: `string`):

TikTok API version, e.g. v2. Override only if TikTok bumps the version.

## Actor input object example

```json
{
  "keywords": [
    "nike",
    "adidas"
  ],
  "advertiserBusinessIds": [
    "3847236290405"
  ],
  "countryCode": "ALL",
  "dateFrom": "20240101",
  "dateTo": "20241231",
  "searchType": "exact_phrase",
  "maxItems": 100,
  "includeDetails": false,
  "apiVersion": "v2"
}
```

# Actor output Schema

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

Dataset containing Tiktok Ads Library Scraper records (ad\_id, advertiser\_name, advertiser\_id, region, first\_shown, last\_shown, status, impressions\_range, video\_url, caption, ad\_url, parse\_confidence).

# 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 = {
    "keywords": [
        "nike"
    ],
    "countryCode": "ALL",
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("bovi/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 = {
    "keywords": ["nike"],
    "countryCode": "ALL",
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("bovi/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 '{
  "keywords": [
    "nike"
  ],
  "countryCode": "ALL",
  "maxItems": 100
}' |
apify call bovi/tiktok-ads-library-scraper --silent --output-dataset

```

## MCP server setup

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