# TikTok Ad Library Scraper — DSA Commercial Content Spy (`dltik/tiktok-ad-library`) Actor Scrape TikTok's official DSA-mandated public Ad Library (library.tiktok.com). Search by keyword or browse all ads per country. Get advertiser, video URL, cover, image URLs, first/last shown dates, estimated audience, spend and impressions. Headless bootstrap + HTTP pagination. - **URL**: https://apify.com/dltik/tiktok-ad-library.md - **Developed by:** [Walid](https://apify.com/dltik) (community) - **Categories:** Marketing, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Ad Library Scraper — DSA Commercial Content Spy **TikTok Ad Library Scraper** extracts ads from TikTok's **official DSA-mandated public Ad Library** (library.tiktok.com) — every ad that ran in the EU, with the DSA premium fields: **advertiser, dates, estimated audience tier, impression count, spend, and the direct video URL**. Different from the Creative Center: this is the full DSA library (FR alone has 83M+ ads). Browse all ads per country or search by keyword. Headless bootstrap + pure HTTP pagination. > ⭐ **Found this useful?** Click the **Bookmark** button at the top of [this page](https://apify.com/dltik/tiktok-ad-library) — it's the single strongest signal that keeps this actor visible to others. One click. No signup beyond your existing Apify account. --- ### What can TikTok Ad Library Scraper do? - 🌍 **Browse the full DSA library** per country (FR, DE, IT, ES, NL, PL...) — 83M+ ads in FR alone - 🔍 **Search by keyword** in ad content / advertiser names - 📊 **DSA premium fields** — `estimated_audience` (tier 0-1K, 1K-10K, etc.), `impressions`, `spent` - 🎬 **Direct video URLs + cover** + image URLs - 📅 **Period filter** — last N days - 🧭 **2 sections** — `ads` (standard) and `other` (other commercial content) - 📈 **Sort modes** — newest / oldest / highest impressions - ⚡ **Headless bootstrap (~10s) + HTTP pagination** — 60 ads in ~25s --- ### What data can you extract per TikTok ad? | Field | Description | |-------|-------------| | `ad_id` | TikTok DSA library ad ID | | `advertiser_name` | Advertiser display name | | `advertiser_id` | Internal advertiser/business ID | | `audit_status` | DSA moderation status | | `type` | Ad type code | | `first_shown_ms` | First shown date (epoch ms) | | `last_shown_ms` | Last shown date (epoch ms) | | `estimated_audience` | DSA audience tier (e.g. `0-1K`, `1K-10K`, `10K-100K`...) | | `impressions` | Number of impressions reported by TikTok | | `spent` | Spend disclosure | | `video_url` | Direct video URL | | `cover_url` | Cover image | | `image_urls` | All image URLs (carousel ads) | | `region` | Country code | | `detail_url` | Direct link to the DSA detail page | --- ### How to spy on TikTok ads (DSA library) 1. **[Create a free Apify account](https://apify.com/sign-up)** — no credit card required 2. **Open [TikTok Ad Library Scraper](https://apify.com/dltik/tiktok-ad-library)** in Apify Store 3. **Pick a country** (default `FR`) and **optionally** a `query` keyword 4. **Pick a period** (default 30 days) and **sort** (newest / impressions) 5. **Click Start** — ads stream within seconds --- ### How much does it cost to spy on TikTok DSA ads? **$0.002 per ad** ($2 per 1,000 ads). One-shot headless bootstrap (~10s once per run) then pure HTTP pagination. | Run size | Ads | Apify cost | Time | |----------|-----|------------|------| | Quick test | 12 | ~$0.024 | ~15s | | Standard | 60 | ~$0.12 | ~25s | | Deep | 240 | ~$0.48 | ~1min | | Massive | 1000 | ~$2 | ~3min | --- ### Input parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `region` | string | `FR` | ISO 2-letter code (EU + supported globals) | | `query` | string | — | Keyword to search; empty = browse all ads | | `section` | string | `ads` | `ads` or `other` (other commercial content) | | `periodDays` | integer | `30` | Lookback window in days | | `order` | string | `last_shown_date,desc` | `last_shown_date,desc/asc`, `first_shown_date,desc`, `impression,desc` | | `maxResults` | integer | `60` | Cap on total ads returned | | `useResidentialProxy` | boolean | `false` | Enable only if you hit rate limits | --- ### Output example ```json { "ad_id": "1866718100189281", "advertiser_name": "olesiashopart", "advertiser_id": null, "audit_status": "1", "type": "2", "first_shown_ms": 1780241349000, "last_shown_ms": 1780241349000, "estimated_audience": "0-1K", "impressions": 0, "spent": null, "video_url": "https://library.tiktok.com/api/v1/cdn/.../video.mp4", "cover_url": "https://...cover.image", "image_urls": [], "region": "FR", "detail_url": "https://library.tiktok.com/ads/detail/?ad_id=1866718100189281" } ```` *** ### Use cases - **EU competitor ad spy** — every TikTok ad shown in any EU country since 2023 - **DSA compliance research** — pull the official transparency record per advertiser - **Agency reporting** — full library coverage (way wider than the Creative Center's curated Top Ads) - **AI training data** — bulk video URLs + DSA-tier labels - **Dropshipping research** — sort by `impression,desc` to surface winning creatives *** ### Use the actor via API **Python:** ```python import requests run = requests.post( "https://api.apify.com/v2/acts/dltik~tiktok-ad-library/runs", headers={"Authorization": "Bearer YOUR_APIFY_TOKEN"}, json={"region": "FR", "query": "nike", "periodDays": 30, "maxResults": 60} ).json() print("Run started:", run["data"]["id"]) ``` **curl:** ```bash curl -X POST "https://api.apify.com/v2/acts/dltik~tiktok-ad-library/runs" \ -H "Authorization: Bearer YOUR_APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"region":"FR","query":"nike","periodDays":30,"maxResults":60}' ``` *** ### FAQ **What's the difference vs the TikTok Creative Center scraper?** TikTok runs **two** transparency products. The **Creative Center** showcases a curated "Top Ads" feed for advertiser inspiration (with CTR + likes). The **DSA Ad Library** (this scraper) is the official EU-mandated public record of every ad shown — far wider coverage, includes the DSA-mandated fields (audience tier, impressions, spend). Use this for compliance, deep competitor sweeps, EU-targeted research. **Do I need a TikTok account?** No. The DSA library is a public transparency tool. The scraper bootstraps a session token in a headless browser (once per run) then paginates over HTTP — no login, no cookies. **Why does the actor briefly run Chromium?** The library API requires an `x-ccl-str` token generated client-side. We capture one fresh token in ~10s via headless Chromium then reuse it for the rest of the run via fast HTTP calls. **Advanced: refresh signing without redeploy.** If TikTok rotates the validity window and the bundled fallback expires, override two env vars in the Apify console: `TT_CCL_STR` (the token), `TT_CCL_REFERER` (the page URL it came from). Copy them from the request headers of any `/api/v1/search` call in DevTools. *** ⭐ **Found this TikTok Ad Library Scraper useful? Bookmark it** — Apify ranks actors by bookmarks, so it's the strongest single signal for Store visibility. ### Other scrapers by dltik | Actor | What it does | Price | |-------|-------------|-------| | [Facebook Ads Library Scraper](https://apify.com/dltik/facebook-ads-scraper) | Meta (Facebook + Instagram) ad library spy with DSA detail enrichment | $0.75/1K | | [Google Ads Transparency Scraper](https://apify.com/dltik/google-ads-transparency) | Google Search, YouTube, Display ad spy via official Ad Transparency Center | $0.8/1K | | [LinkedIn Ad Library Scraper](https://apify.com/dltik/linkedin-ad-library) | B2B competitor ad spy from LinkedIn's public Ad Library | $2/1K | | [TikTok Creative Center](https://apify.com/dltik/tiktok-creative-center) | Curated Top Ads with CTR + likes + MP4 video URL | $2/1K | # Actor input Schema ## `region` (type: `string`): ISO 2-letter country code (EU + global supported regions). TikTok's DSA Ad Library is EU-focused (FR, DE, IT, ES, NL, PL...). ## `query` (type: `string`): Optional keyword to search ad content / advertiser name. Empty = browse all ads. ## `section` (type: `string`): Which library section to scrape. ## `periodDays` (type: `integer`): Look back this many days (default 30). ## `order` (type: `string`): Order results by this field. ## `maxResults` (type: `integer`): Total cap (paginated, ~12 per page). ## `useResidentialProxy` (type: `boolean`): Enable only if you hit rate limits on large runs. ## `proxyConfiguration` (type: `object`): Advanced override (only used when 'Use residential proxy' is on). ## Actor input object example ```json { "region": "FR", "section": "ads", "periodDays": 30, "order": "last_shown_date,desc", "maxResults": 60, "useResidentialProxy": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): List of TikTok ads from the DSA library. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "region": "FR" }; // Run the Actor and wait for it to finish const run = await client.actor("dltik/tiktok-ad-library").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "region": "FR" } # Run the Actor and wait for it to finish run = client.actor("dltik/tiktok-ad-library").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 '{ "region": "FR" }' | apify call dltik/tiktok-ad-library --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=dltik/tiktok-ad-library", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ad Library Scraper — DSA Commercial Content Spy", "description": "Scrape TikTok's official DSA-mandated public Ad Library (library.tiktok.com). Search by keyword or browse all ads per country. Get advertiser, video URL, cover, image URLs, first/last shown dates, estimated audience, spend and impressions. Headless bootstrap + HTTP pagination.", "version": "1.0", "x-build-id": "CSHMeCklVjQdkupEc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dltik~tiktok-ad-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dltik-tiktok-ad-library", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/dltik~tiktok-ad-library/runs": { "post": { "operationId": "runs-sync-dltik-tiktok-ad-library", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/dltik~tiktok-ad-library/run-sync": { "post": { "operationId": "run-sync-dltik-tiktok-ad-library", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "region": { "title": "Region", "type": "string", "description": "ISO 2-letter country code (EU + global supported regions). TikTok's DSA Ad Library is EU-focused (FR, DE, IT, ES, NL, PL...).", "default": "FR" }, "query": { "title": "Keyword", "type": "string", "description": "Optional keyword to search ad content / advertiser name. Empty = browse all ads." }, "section": { "title": "Section", "enum": [ "ads", "other" ], "type": "string", "description": "Which library section to scrape.", "default": "ads" }, "periodDays": { "title": "Period (days)", "minimum": 1, "maximum": 365, "type": "integer", "description": "Look back this many days (default 30).", "default": 30 }, "order": { "title": "Sort", "enum": [ "last_shown_date,desc", "last_shown_date,asc", "first_shown_date,desc", "impression,desc" ], "type": "string", "description": "Order results by this field.", "default": "last_shown_date,desc" }, "maxResults": { "title": "Max ads", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Total cap (paginated, ~12 per page).", "default": 60 }, "useResidentialProxy": { "title": "Use residential proxy (optional)", "type": "boolean", "description": "Enable only if you hit rate limits on large runs.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Advanced override (only used when 'Use residential proxy' is on).", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```