# TikTok Ads Scraper (`data_xplorer/tiktok-ads-scraper`) Actor

💸🥇 THE MOST COMPLETE AND CHEAPEST TIKTOK ADS SCRAPER. 🥇💸 Two modes: Ads Library (EU transparency, targeting, spend) + Top Ads (Creative Center, engagement metrics, 80+ countries). Search by keyword, advertiser, and industry. Extract videos, performance data, and creative assets.

- **URL**: https://apify.com/data\_xplorer/tiktok-ads-scraper.md
- **Developed by:** [Data Xplorer](https://apify.com/data_xplorer) (community)
- **Categories:** AI, Lead generation, Social media
- **Stats:** 293 total users, 79 monthly users, 100.0% runs succeeded, 4 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Scraper: Library + Top Ads

The most complete TikTok advertising intelligence tool on Apify. Two powerful modes in one Actor:

- **📚 Ads Library**: EU transparency data from [library.tiktok.com](https://library.tiktok.com)
- **🎯 Top Ads**: Performance-ranked ads from [TikTok Creative Center](https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en)

![TikTok Ads Scraper](https://i.ibb.co/m105zws/fil-u-E21-Yt-Zv-Fy2-Nq-XBE-1.jpg)

***

### 🎯 Two Modes, One Actor

#### 📚 Ads Library Mode (EU Transparency)

Access TikTok's official Ad Library for the European market. Get full transparency data: advertiser info, targeting, audience size, spend estimates, impressions, **per-country reach with age × gender breakdowns**, advertiser profile, media assets, and more.

**Best for:** Compliance research, competitor monitoring in EU/EEA, advertiser-level analysis, spend & reach insights.

#### 🎯 Top Ads Mode (Creative Center)

Access TikTok's Creative Center Top Ads, a curated ranking of the best-performing ads worldwide. Get engagement metrics (likes, CTR, budget level), video assets, and industry classification.

**Best for:** Creative inspiration, ad benchmarking, industry trend analysis, competitive intelligence.

***

### 💎 Key Features

| Feature | Ads Library | Top Ads |
|---------|:-----------:|:-------:|
| 🌍 Global coverage | EU/EEA countries | 80+ countries |
| 🔍 Keyword search | ✅ | ✅ |
| 🏢 Advertiser search | ✅ | - |
| 🔗 Direct URL import | ✅ | - |
| ❤️ Engagement metrics (likes, CTR, budget) | - | ✅ |
| 📈 Impressions & audience estimates | ✅ (with details) | - |
| 🗺️ Per-country reach + age × gender breakdown | ✅ (with details) | - |
| 🔢 Numbers parsed to integers (min/max) | ✅ | - |
| 💰 Spend estimates | ✅ (with details) | - |
| 🎯 Targeting data (age, gender, region, languages, OS…) | ✅ (with details) | - |
| 👤 Advertiser profile + TikTok account | ✅ (with details) | Brand name |
| 🏷️ Industry & objective classification | - | ✅ |
| 🎬 Video URLs | Up to 1080p | 720p |
| ⚡ Speed | ~2-5 ads/sec | ~20 ads/sec |

> 💡 **Tip:** In Library mode, enable **"Fetch Ad Details"** to get impressions, spend, full targeting, advertiser profile, and the reliable **per-country reach** (with age × gender breakdowns). Without it, scraping is faster but only returns basic ad info.

> 🔢 **All numeric ranges are parsed.** Fields like `Ad Audience`, `Ad Target Audience Size` and every reach value are returned as an object `{ "raw": "11.7M-14.2M", "min": 11700000, "max": 14200000 }` — keep the human-readable text in `raw`, and sort/filter/aggregate directly on `min` / `max`.

***

### 📚 Ads Library Mode

#### Search Options

1. **🔤 Keyword Search**: Search ads by content keywords
2. **🏢 Advertiser Name**: Find all ads from a specific advertiser (optionally with Advertiser ID for precision)
3. **🌐 Direct URL**: Paste any TikTok Ads Library URL and all parameters are auto-extracted

#### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| mode | string | `"library"` | Set to `"library"` |
| region | string | `"all"` | Country code (FR, DE, GB, etc.) or "all" |
| startDate | string | `"2025-01-01"` | Start date (YYYY-MM-DD) |
| endDate | string | `""` | End date (empty = today) |
| queryType | string | `"2"` | 1 = Keyword, 2 = Advertiser Name, url = Direct URL |
| query | string | `""` | Search term, advertiser name, or full URL |
| advertiserBizId | string | `""` | Optional advertiser business ID |
| maxAds | number | `20` | Maximum ads to collect |
| fetchDetails | boolean | `true` | Fetch targeting, advertiser profile, audience, spend, impressions, and per-country reach |
| detailConcurrency | number | `6` | Number of ad-detail requests fetched in parallel |
| proxyConfiguration | object | Apify Proxy | Proxy settings |

#### Input Example: Advertiser Name + ID

```json
{
  "mode": "library",
  "region": "FR",
  "startDate": "2026-01-01",
  "endDate": "2026-06-01",
  "queryType": "2",
  "query": "LEVI STRAUSS & CO.",
  "advertiserBizId": "6886458055832109825",
  "maxAds": 10,
  "fetchDetails": true
}
```

#### Input Example: Keyword Search

```json
{
  "mode": "library",
  "region": "GB",
  "startDate": "2025-01-01",
  "queryType": "1",
  "query": "football",
  "maxAds": 20,
  "fetchDetails": true
}
```

#### Input Example: Direct TikTok URL

```json
{
  "mode": "library",
  "queryType": "url",
  "query": "https://library.tiktok.com/ads?region=FR&start_time=1777123937000&end_time=1779715937000&adv_name=LEVI%20STRAUSS%20%26%20CO.&adv_biz_ids=6886458055832109825&query_type=2&sort_type=last_shown_date,desc",
  "maxAds": 10,
  "fetchDetails": true
}
```

#### Output Example (Library, with fetchDetails)

```json
{
  "AD ID": "1867625146670401",
  "Advertiser Name": "COCA COLA HBC POLSKA SP Z O O",
  "Ad Title": "Wygrywaj!",
  "AD Preview": "https://p16-common-sign.tiktokcdn.com/...",
  "Ad Dates": [
    { "FirstShown": "2026-06-12", "FirstShownTimestamp": 1781222400 },
    { "LastShown": "2026-06-14", "LastShownTimestamp": 1781395200 }
  ],
  "Ad Audience": { "raw": "1M-10M", "min": 1000000, "max": 10000000 },
  "Ad Details": [
    { "Estimated Audience": "1M-10M" },
    { "Spent": "" },
    { "Impression": "" },
    { "Type": "2" },
    { "Audit Status": "1" },
    { "Advertising Objective": "Reach" },
    { "Call To Action": "Learn more" },
    { "External URL": "https://cokeurl.com/KuM89D?utm_source=tiktok" }
  ],
  "Ad Media": [
    "Video 1: https://library.tiktok.com/api/v1/cdn/...",
    "Image 1: https://p16-common-sign.tiktokcdn.com/..."
  ],
  "Ad Targeting": {
    "regions": ["PL"],
    "age": ["18-24", "25-34", "35-44", "45-54", "55+"],
    "gender": ["female", "male", "unknown"],
    "os": ["ALL"],
    "languages": [],
    "high_spending_power": "No",
    "audience": "No"
  },
  "Ad Reach": {
    "total_region": 1,
    "total_impressions": { "raw": "1M-10M", "min": 1000000, "max": 10000000 },
    "by_country": [
      {
        "region": "PL",
        "impressions": { "raw": "1.5M", "min": 1500000, "max": 1500000 },
        "breakdowns": [
          { "age": "18-24", "gender": "FEMALE", "impressions": { "raw": "252K", "min": 252000, "max": 252000 } },
          { "age": "25-34", "gender": "FEMALE", "impressions": { "raw": "352K", "min": 352000, "max": 352000 } },
          { "age": "25-34", "gender": "MALE", "impressions": { "raw": "273K", "min": 273000, "max": 273000 } }
        ]
      }
    ]
  },
  "Advertiser": {
    "name": "COCA COLA HBC POLSKA SP Z O O",
    "adv_biz_ids": "6876461641299395330",
    "registry_location": "United Kingdom",
    "sponsor": "MEDIACOM UK LIMITED",
    "tiktok_account": {
      "username": "cocacola",
      "display_name": "Coca-Cola",
      "follower_count": "4.2M",
      "account_type": "BLUEV_BA",
      "profile_web_link": "https://www.tiktok.com/share/user/..."
    }
  },
  "Ad Sponsor": "MEDIACOM UK LIMITED",
  "Ad Target Audience Size": { "raw": "11.7M-14.2M", "min": 11700000, "max": 14200000 },
  "Ad Detail URL": "https://library.tiktok.com/ads/detail/?ad_id=1867625146670401"
}
```

#### Library Metrics (with fetchDetails enabled)

> ℹ️ Numeric fields below are returned as `{ raw, min, max }`: `raw` is the original text (e.g. `"1.5M"`), `min`/`max` are integers (equal for single values, distinct for ranges, `null` when empty).

| Field | Description |
|-------|-------------|
| `Ad Title` | Title/headline (caption) of the ad creative |
| `Ad Audience` | Estimated audience range as `{ raw, min, max }` (e.g. "1M-10M") — broad, less reliable |
| `Ad Reach` | **Reliable per-country reach**: total regions, total impressions, and for each country the exact impressions **plus a full age × gender breakdown** — every impressions value is a `{ raw, min, max }` object |
| `Ad Details` | Spend, impressions, type, audit status, advertising objective, call to action, and external (landing) URL |
| `Ad Targeting` | Regions, enabled age groups, gender, languages, cities, provinces, OS, high spending power, audience signals |
| `Advertiser` | Advertiser profile: name, business IDs, registry location, sponsor, and linked TikTok account (username, followers, account type, profile link) |
| `Ad Sponsor` | Name of the sponsoring entity |
| `Ad Target Audience Size` | Total estimated target audience as `{ raw, min, max }` (e.g. "11.7M-14.2M") |
| `Ad Media` | Direct URLs to videos, cover images, and creatives |

> 🎯 **Which reach number should I trust?** Use `Ad Reach.by_country[].impressions.min` (or `.raw`) — it's the accurate "Reach by location" figure from TikTok's detail page. The top-level `Ad Audience` ("Unique users seen") is only a broad estimate range.

***

### 🎯 Top Ads Mode

#### Filters

- **🔍 Keyword**: Search by brand, product, or topic
- **🌍 Countries**: Multi-select from 80+ countries
- **🏷️ Industries**: 21 parent categories + 200+ sub-industries
- **🎯 Objectives**: Traffic, Conversions, App Installs, Video Views, Reach, Lead Gen, Product Sales
- **🗣️ Language**: Filter by ad language (17 languages)
- **❤️ Likes percentile**: Top 1-20%, 21-40%, etc.
- **📅 Time period**: Last 7 days, 30 days, or 6 months
- **📊 Sort by**: Likes, Reach, CTR, CVR, 2s/6s view rates

#### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| mode | string | - | Set to `"top_ads"` |
| topAdsKeyword | string | `""` | Search keyword (leave empty to browse all) |
| topAdsCountryCode | array | `[]` | Country codes, e.g. `["FR", "DE"]` |
| topAdsPeriod | string | `"7"` | `"7"`, `"30"`, or `"180"` days |
| topAdsOrderBy | string | `"like"` | Sort: like, impression, ctr, cvr, play\_2s\_rate, play\_6s\_rate |
| topAdsIndustry | array | `[]` | Industry IDs (parent or sub-industry) |
| topAdsObjective | array | `[]` | Objective IDs: 1=Traffic, 2=App, 3=Conversions, etc. |
| topAdsLanguage | string | `""` | Language code (fr, en, de, etc.) |
| topAdsLikeRange | string | `""` | Likes percentile: 1-5 |
| topAdsMaxItems | number | `100` | Maximum ads to collect (up to 500) |

#### Input Example: Top Ads in France (Education)

```json
{
  "mode": "top_ads",
  "topAdsCountryCode": ["FR"],
  "topAdsPeriod": "30",
  "topAdsOrderBy": "like",
  "topAdsIndustry": ["10000000000"],
  "topAdsLanguage": "fr",
  "topAdsMaxItems": 50
}
```

#### Input Example: Keyword Search

```json
{
  "mode": "top_ads",
  "topAdsKeyword": "netflix",
  "topAdsCountryCode": ["FR", "US"],
  "topAdsPeriod": "30",
  "topAdsOrderBy": "like",
  "topAdsMaxItems": 20
}
```

#### Input Example: Sub-industry Filter

```json
{
  "mode": "top_ads",
  "topAdsCountryCode": ["FR"],
  "topAdsPeriod": "30",
  "topAdsIndustry": ["14103000000", "14104000000"],
  "topAdsObjective": ["3"],
  "topAdsMaxItems": 40
}
```

#### Output Example (Top Ads)

```json
{
  "id": "7636363707227226130",
  "ad_title": "Des fiches prêtes à apprendre pour booster tes révisions CRPE",
  "brand_name": "Not Mention",
  "like": 585,
  "cost": 1,
  "cost_readable": "Medium",
  "ctr": 0.14,
  "ctr_readable": "Top 14%",
  "industry_key": "label_10101000000",
  "industry": "Primary & Secondary Education & K-12",
  "objective_key": "campaign_objective_conversion",
  "objective": "Conversions",
  "video_duration": 10.467,
  "video_cover": "https://p16-common-sign.tiktokcdn.com/...",
  "video_url_720p": "https://v16m-default.tiktokcdn.com/...",
  "video_width": 720,
  "video_height": 1280,
  "creative_center_url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?ad_id=7636363707227226130"
}
```

#### Top Ads Metrics

| Field | Description |
|-------|-------------|
| `like` | Number of likes on the ad |
| `cost_readable` | Budget level: **Low**, **Medium**, or **High** |
| `ctr_readable` | CTR percentile ranking (e.g. "Top 14%" = outperforms 86% of ads) |
| `industry` | Human-readable industry label (200+ categories) |
| `objective` | Campaign objective: Traffic, Conversions, App Installs, etc. |
| `video_url_720p` | Direct download URL for the ad video (720p) |

***

### 💡 Use Cases & Ideas

#### 🏢 For Marketing & Ad Agencies

- **Creative swipe files**: Build a library of top-performing TikTok ads in your client's industry. Filter by country, objective, and sub-industry to find exactly the right inspiration.
- **Pitch preparation**: Show clients what competitors are running and what's working best. Use budget and CTR data to benchmark performance.
- **Ad spend monitoring**: Track how much competitors invest across regions with Library mode's spend estimates.

#### 🛍️ For E-Commerce & DTC Brands

- **Competitor tracking**: Monitor what ads your competitors are running in real-time across EU markets. Get notified when new campaigns launch.
- **Creative inspiration**: Find the highest-engagement ads in your product category (Skincare, Cosmetics, Fashion...) and study what makes them work.
- **Market entry research**: Before launching in a new country, analyze what ad formats, messages, and budgets work best in that market.

#### 📊 For Data Analysts & Researchers

- **Industry benchmarking**: Collect hundreds of ads across industries to build performance benchmarks (CTR percentiles, budget tiers, engagement rates).
- **Reach analysis**: Use Library mode's per-country reach and age × gender breakdowns (with integer `min`/`max` values) to map exactly who each campaign reached, market by market.
- **Trend detection**: Run weekly scrapes to track which industries, objectives, and ad formats are gaining traction over time.
- **Academic research**: Study advertising patterns, targeting strategies, and political ad transparency across the EU.

#### 🎯 For Media Buyers & Performance Marketers

- **Winning ad formats**: Sort by CTR or conversion rate to find the highest-performing creative formats in your niche.
- **Budget intelligence**: Understand whether top performers are Low, Medium, or High budget, and find opportunities where low-budget ads outperform.
- **Targeting insights**: Use Library mode's age, gender, regional targeting and per-country reach data to refine your own audience strategy.

#### 🔗 Integration Ideas

- **Feed into Google Sheets or Airtable**: Use Apify integrations to automatically push new ads into your creative tracking spreadsheet.
- **Build a Slack alert**: Get notified when a competitor launches a new ad or when a top-performing ad appears in your industry.
- **Power a dashboard**: Connect the output to Looker Studio, Tableau, or any BI tool for real-time ad intelligence dashboards.
- **Train AI models**: Use the video URLs and ad copy to train creative analysis models or generate ad variations.

***

### 🤝 Support & Resources

Found a bug or want to request a feature? Open an issue.

**❤️ Enjoying the scraper?** Leave a review [here](https://console.apify.com/actors/rFFzT2mRuOd1K4iTM/reviews)

# Actor input Schema

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

Choose which TikTok data source to scrape.

## `region` (type: `string`):

Region code for which you want to scrape ads

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

Start date for ads (format: YYYY-MM-DD)

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

End date for ads (format: YYYY-MM-DD). Leave empty for current date.

## `queryType` (type: `string`):

Type of search query

## `query` (type: `string`):

For Keyword: enter a search term. For Advertiser Name: enter the exact advertiser name. For URL: paste a full TikTok Ads Library URL. Leave empty to search all ads.

## `advertiserBizId` (type: `string`):

Optional advertiser business ID (numeric). Only used when Query Type is 'Advertiser Name'.

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

Maximum number of ads to scrape

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

Enable to fetch detailed information for each ad (targeting, sponsor, etc.).

## `topAdsKeyword` (type: `string`):

Search top ads by keyword (brand name, product, topic…). Leave empty to browse all top ads.

## `topAdsCountryCode` (type: `array`):

Select one or more countries to filter top ads (leave empty for global results).

## `topAdsPeriod` (type: `string`):

Number of days to look back.

## `topAdsOrderBy` (type: `string`):

Sort top ads by metric.

## `topAdsIndustry` (type: `array`):

Select one or more industries or sub-industries to filter top ads (leave empty for all).

## `topAdsObjective` (type: `array`):

Select one or more campaign objectives to filter top ads (leave empty for all objectives).

## `topAdsLanguage` (type: `string`):

Filter ads by language. Leave empty for all languages.

## `topAdsLikeRange` (type: `string`):

Filter by likes performance percentile. Leave empty for all.

## `topAdsMaxItems` (type: `integer`):

Maximum number of top ads to return.

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

Proxy for Ads Library mode. Top Ads mode runs without proxy for best performance.

## Actor input object example

```json
{
  "mode": "library",
  "region": "all",
  "startDate": "2025-01-01",
  "endDate": "",
  "queryType": "1",
  "query": "Netflix",
  "advertiserBizId": "",
  "maxAds": 100,
  "fetchDetails": false,
  "topAdsKeyword": "",
  "topAdsPeriod": "7",
  "topAdsOrderBy": "like",
  "topAdsLanguage": "",
  "topAdsLikeRange": "",
  "topAdsMaxItems": 100,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `topAdsOverview` (type: `string`):

No description

## `topAdsAnalytics` (type: `string`):

No description

# 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 = {
    "startDate": "2025-01-01",
    "queryType": "1",
    "query": "Netflix",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("data_xplorer/tiktok-ads-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 = {
    "startDate": "2025-01-01",
    "queryType": "1",
    "query": "Netflix",
    "proxyConfiguration": { "useApifyProxy": True },
}

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

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

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

```

## CLI example

```bash
echo '{
  "startDate": "2025-01-01",
  "queryType": "1",
  "query": "Netflix",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call data_xplorer/tiktok-ads-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=data_xplorer/tiktok-ads-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/rFFzT2mRuOd1K4iTM/builds/9GuNtmTVYe2utt14t/openapi.json