# TikTok Ads Library Scraper (`khadinakbar/tiktok-ads-library-scraper`) Actor Search TikTok's public Ads Library by advertiser, keyword, business ID, or copied library URL. Returns creative media, advertiser, status, dates, audience estimates, targeting details, and source links. Use for EU/EEA competitor-ad research. Costs $0.006 per ad plus $0.00005 start. - **URL**: https://apify.com/khadinakbar/tiktok-ads-library-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $6.00 / 1,000 tiktok ad scrapeds 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 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 Ads Library Scraper Search TikTok's public Ads Library by keyword, advertiser, advertiser business ID, or a copied filtered library URL. It returns one structured record per ad, including advertiser identity, creative media URLs, public dates and status, audience estimates, source links, and—when enabled—public targeting details. Use it for EU/EEA competitor-ad research, creative swipe files, campaign monitoring, and public advertising-transparency analysis. Do not use it for TikTok profiles, organic posts, TikTok Creative Center Top Ads, private campaign data, or Ads Manager account data. ### What you receive | Field | Meaning | | --- | --- | | `adId`, `adDetailUrl`, `libraryUrl` | Stable public ad identifier and reproducible source links | | `advertiserName`, `advertiserBusinessId`, `sponsor` | Advertiser identity as exposed by TikTok | | `title`, `callToAction`, `landingPageUrl` | Public creative copy and destination fields | | `videoUrls`, `imageUrls`, `coverImageUrls` | Public creative assets; media links may expire | | `firstShownAt`, `lastShownAt`, `auditStatus` | Public lifecycle fields | | `estimatedAudience`, `impressions` | Public aggregate transparency values when available | | `targetCountries`, `targetAudienceSize`, `targetInterests` | Optional public detail fields when `includeDetails` is enabled | | `source`, `scrapedAt` | Provenance and extraction time | The default dataset view is concise enough for automation. `RUN_SUMMARY` always records the terminal outcome, saved count, charge counters, stop reason, and warnings. ### Inputs Use one of these approaches: 1. Paste a filtered `libraryUrl` from `https://library.tiktok.com/ads`. It preserves its country, date range, and advertiser/keyword filters; results use TikTok's verified newest-last-shown order. 2. Build a search with `country`, `searchQuery`, optional `advertiserBusinessId`, and date range. Keyword example: ```json { "country": "DE", "searchQuery": "adidas", "searchType": "keyword", "dateFrom": "2026-04-01", "maxResults": 25, "includeDetails": false } ```` Exact advertiser example: ```json { "country": "DE", "searchQuery": "adidas AG", "searchType": "advertiser", "advertiserBusinessId": "6885261436319171329", "maxResults": 10, "includeDetails": true } ``` URL-first example: ```json { "libraryUrl": "https://library.tiktok.com/ads?region=DE&start_time=1767225600000&end_time=1769904000000&adv_name=adidas&adv_biz_ids=&query_type=1&sort_type=last_shown_date%2Cdesc", "maxResults": 20, "includeDetails": true } ``` ### Pricing This actor uses Pay per event plus Apify platform usage: - Actor start: `$0.00005` - Validated ad written: `$0.006` per record - Public ad-detail enrichment: `$0.002` per successful detail response `maxResults` is the primary event-cost cap. A 20-ad run without details has at most `$0.12005` in event charges; platform usage is billed separately by Apify. Media URL availability, public fields, and result counts are determined by TikTok's library. ### Reliability and outcomes The actor uses a fresh Apify Residential browser session for each retry, initializes TikTok's public library session before querying, and validates each row before the coupled write-and-charge operation. It never invents a minimal record to rescue a failed write. Every run writes both `OUTPUT` and `RUN_SUMMARY` with one outcome: - `COMPLETE`: all returned records were written cleanly. - `PARTIAL`: useful records were written, but some details or rows could not be completed. - `VALID_EMPTY`: TikTok replied successfully but no ads matched. - `INVALID_INPUT`: the search was missing or invalid; correct the supplied field. - `UPSTREAM_FAILED`: TikTok's public library or the browser session failed before useful data was returned. ### Limits and responsible use - Data comes only from TikTok's public Ads Library, whose coverage is country-specific and can change. - This actor does not log in, request user cookies, access private data, or bypass account controls. - `includeDetails` retrieves only public transparency fields and is slower than a creative-only run. - Video and image URLs can be signed and short-lived; rerun the actor to refresh them. - For decisions involving ad use, targeting, or compliance, retain the source URL and verify time-sensitive fields directly in TikTok's public library. - If TikTok marks a filter combination as an invalid search, the actor returns `INVALID_INPUT` without retrying; adjust the country, date range, advertiser, or copied URL. # Actor input Schema ## `libraryUrl` (type: `string`): Use this when you already have a filtered https://library.tiktok.com/ads URL to reproduce exactly. Paste a URL containing region, date range, and advertiser or keyword filters, for example https://library.tiktok.com/ads?region=DE\&adv\_name=adidas\&query\_type=1. Its filters override the individual search fields. Do not paste a TikTok profile, ad-detail, Creative Center, or Ads Manager URL. ## `country` (type: `string`): Use this when building a public Ads Library search rather than pasting libraryUrl. Select one country where TikTok exposes the transparent ad record, for example DE for Germany. Defaults to DE and also selects a matching residential browser session. This is not the country where your own company is located. ## `searchQuery` (type: `string`): Use this when searching the public library by advertiser name or words in an ad, for example adidas. It accepts one phrase and defaults to adidas for a working health-check search. Choose searchType to say whether the phrase is a keyword or advertiser-name search. This is not an ad ID, TikTok handle, or profile URL. ## `searchType` (type: `string`): Use this to tell TikTok whether searchQuery is a keyword or an advertiser name. Choose keyword for words appearing in creatives and advertiser for a brand, for example adidas AG. Defaults to keyword and only changes the public library search interpretation. It does not perform an exact business-ID lookup; use advertiserBusinessId for that. ## `advertiserBusinessId` (type: `string`): Use this when you know TikTok's advertiser business ID and need an exact advertiser filter. Enter digits such as 6885261436319171329; it can be combined with searchQuery. Leave blank when you only know a brand name or keyword. This is not an ad ID or a TikTok user ID. ## `dateFrom` (type: `string`): Use this to set the inclusive beginning of the public-library date range in YYYY-MM-DD format, for example 2026-01-01. If omitted, the actor uses the preceding 90 days to keep searches bounded and predictable. Use an earlier date only when the target country and advertiser need historical coverage. This is not a time zone, timestamp, or an ad creation-date guarantee. ## `dateTo` (type: `string`): Use this to set the inclusive end of the public-library date range in YYYY-MM-DD format, for example 2026-03-31. If omitted, the actor uses the time the run starts. It must be on or after dateFrom. This is not a duration, a relative date phrase, or a future schedule. ## `maxResults` (type: `integer`): Use this to cap validated Ads Library records written to the dataset. Enter an integer from 1 to 200; the default is 20 and each saved record charges the ad-scraped event. Keep it small for a quick check and raise it only for a bounded research job. This is not a page count or a guarantee that TikTok has that many matches. ## `includeDetails` (type: `boolean`): Use this when you need the public detail endpoint's advertiser, targeting, audience-size, and region breakdown fields. It defaults to false to keep runs fast and adds a detail-enriched event only after a detail response succeeds. Enable it for compliance or targeting analysis, not for a basic creative swipe file. It never accesses private advertiser or Ads Manager data. ## `requestTimeoutSecs` (type: `integer`): Use this to set the navigation and public-library request timeout in seconds. Enter a value from 20 to 120; the default is 60 and retries rotate the residential browser session. Increase it only for a slow target response, not to bypass an access block. This is not the overall Apify run timeout. ## Actor input object example ```json { "libraryUrl": "https://library.tiktok.com/ads?region=DE&start_time=1767225600000&end_time=1769904000000&adv_name=adidas&adv_biz_ids=&query_type=1&sort_type=last_shown_date%2Cdesc", "country": "DE", "searchQuery": "adidas", "searchType": "advertiser", "advertiserBusinessId": "6885261436319171329", "dateFrom": "2026-01-01", "dateTo": "2026-03-31", "maxResults": 50, "includeDetails": true, "requestTimeoutSecs": 60 } ``` # Actor output Schema ## `ads` (type: `string`): Dataset records with advertiser identity, media URLs, dates, status, audience estimates, targeting details when selected, and source links. ## `summary` (type: `string`): Machine-readable terminal result including outcome, saved count, warnings, stop reason, and charge counters. ## `runSummary` (type: `string`): Full diagnostics, terminal outcome, billing counters, and warnings for support and automated monitoring. # 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 = { "country": "DE", "searchQuery": "adidas", "searchType": "keyword", "maxResults": 5, "includeDetails": false }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "country": "DE", "searchQuery": "adidas", "searchType": "keyword", "maxResults": 5, "includeDetails": False, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/tiktok-ads-library-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 '{ "country": "DE", "searchQuery": "adidas", "searchType": "keyword", "maxResults": 5, "includeDetails": false }' | apify call khadinakbar/tiktok-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/tiktok-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper", "description": "Search TikTok's public Ads Library by advertiser, keyword, business ID, or copied library URL. Returns creative media, advertiser, status, dates, audience estimates, targeting details, and source links. Use for EU/EEA competitor-ad research. Costs $0.006 per ad plus $0.00005 start.", "version": "1.0", "x-build-id": "TIJKFDa59JfOZpfZ7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-tiktok-ads-library-scraper", "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/khadinakbar~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-tiktok-ads-library-scraper", "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/khadinakbar~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-tiktok-ads-library-scraper", "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": { "libraryUrl": { "title": "TikTok Ads Library URL", "type": "string", "description": "Use this when you already have a filtered https://library.tiktok.com/ads URL to reproduce exactly. Paste a URL containing region, date range, and advertiser or keyword filters, for example https://library.tiktok.com/ads?region=DE&adv_name=adidas&query_type=1. Its filters override the individual search fields. Do not paste a TikTok profile, ad-detail, Creative Center, or Ads Manager URL." }, "country": { "title": "Ad target country", "enum": [ "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" ], "type": "string", "description": "Use this when building a public Ads Library search rather than pasting libraryUrl. Select one country where TikTok exposes the transparent ad record, for example DE for Germany. Defaults to DE and also selects a matching residential browser session. This is not the country where your own company is located.", "default": "DE" }, "searchQuery": { "title": "Advertiser or keyword", "type": "string", "description": "Use this when searching the public library by advertiser name or words in an ad, for example adidas. It accepts one phrase and defaults to adidas for a working health-check search. Choose searchType to say whether the phrase is a keyword or advertiser-name search. This is not an ad ID, TikTok handle, or profile URL.", "default": "adidas" }, "searchType": { "title": "Search interpretation", "enum": [ "keyword", "advertiser" ], "type": "string", "description": "Use this to tell TikTok whether searchQuery is a keyword or an advertiser name. Choose keyword for words appearing in creatives and advertiser for a brand, for example adidas AG. Defaults to keyword and only changes the public library search interpretation. It does not perform an exact business-ID lookup; use advertiserBusinessId for that.", "default": "keyword" }, "advertiserBusinessId": { "title": "Advertiser business ID", "type": "string", "description": "Use this when you know TikTok's advertiser business ID and need an exact advertiser filter. Enter digits such as 6885261436319171329; it can be combined with searchQuery. Leave blank when you only know a brand name or keyword. This is not an ad ID or a TikTok user ID." }, "dateFrom": { "title": "First shown from", "type": "string", "description": "Use this to set the inclusive beginning of the public-library date range in YYYY-MM-DD format, for example 2026-01-01. If omitted, the actor uses the preceding 90 days to keep searches bounded and predictable. Use an earlier date only when the target country and advertiser need historical coverage. This is not a time zone, timestamp, or an ad creation-date guarantee." }, "dateTo": { "title": "Last shown through", "type": "string", "description": "Use this to set the inclusive end of the public-library date range in YYYY-MM-DD format, for example 2026-03-31. If omitted, the actor uses the time the run starts. It must be on or after dateFrom. This is not a duration, a relative date phrase, or a future schedule." }, "maxResults": { "title": "Maximum ads", "minimum": 1, "maximum": 200, "type": "integer", "description": "Use this to cap validated Ads Library records written to the dataset. Enter an integer from 1 to 200; the default is 20 and each saved record charges the ad-scraped event. Keep it small for a quick check and raise it only for a bounded research job. This is not a page count or a guarantee that TikTok has that many matches.", "default": 20 }, "includeDetails": { "title": "Fetch public ad details", "type": "boolean", "description": "Use this when you need the public detail endpoint's advertiser, targeting, audience-size, and region breakdown fields. It defaults to false to keep runs fast and adds a detail-enriched event only after a detail response succeeds. Enable it for compliance or targeting analysis, not for a basic creative swipe file. It never accesses private advertiser or Ads Manager data.", "default": false }, "requestTimeoutSecs": { "title": "Request timeout seconds", "minimum": 20, "maximum": 120, "type": "integer", "description": "Use this to set the navigation and public-library request timeout in seconds. Enter a value from 20 to 120; the default is 60 and retries rotate the residential browser session. Increase it only for a slow target response, not to bypass an access block. This is not the overall Apify run timeout.", "default": 60 } } }, "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 } } } } } } } } } } ```