# TikTok Ads Library Scraper (`trovevault/tiktok-ads-library-scraper`) Actor Extract public TikTok ad creatives with advertiser names, ad IDs, dates, ad text, audience ranges, media URLs, and media-based creative format labels. - **URL**: https://apify.com/trovevault/tiktok-ads-library-scraper.md - **Developed by:** [Trove Vault](https://apify.com/trovevault) (community) - **Categories:** E-commerce, Social media, SEO tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $0.85 / 1,000 ads 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 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 Extract public TikTok ad creatives from supported European Ads Library countries for competitor monitoring, ad research, and creative tracking. The actor searches advertiser names or keywords, then returns ad rows with advertiser names, ad IDs, first and last shown dates, ad copy, video URLs, cover/image assets, and a media-based creative format label. Use it when you want repeatable TikTok ads data for brands such as Nike, ASOS, Temu, or a client competitor list without manually searching TikTok's public Ads Library. ### Why use TikTok Ads Library Scraper? - Monitor new and recently shown TikTok ads by advertiser or keyword. - Build competitor creative swipe files from public video and cover assets. - Track first shown and last shown dates across recurring runs. - Export ad copy, CTA text, video URLs, cover images, and audience ranges when available. - Separate video creatives from image/carousel-like records and records where TikTok did not expose a media URL. - Feed ad intelligence dashboards, agency reports, or downstream creative analyzers. ### What data does TikTok Ads Library Scraper extract? | Field group | Fields | |---|---| | Search context | `target`, `country`, `countryName`, `runId` | | Advertiser identity | `advertiserName` | | Creative identity | `adId`, `status`, `adDetailsUrl` | | Timing | `firstShownDate`, `lastShownDate` | | Creative media | `creativeFormat`, `mediaAvailability`, `videoUrl`, `videoUrls`, `coverImageUrl`, `imageUrls` | | Copy | `title`, `description`, `callToAction`, `creativeText` | | Audience | `estimatedAudience`, `impressionCount` | The actor uses public web endpoints behind TikTok's Ads Library. It does not require a TikTok login for the tested public search path. ### Who uses TikTok Ads Library Scraper? **DTC and e-commerce teams** can monitor competing advertisers and inspect fresh creative angles. **Agencies** can run scheduled client competitor checks and export video assets, cover images, copy, and CTA patterns. **Creative strategists** can build swipe files from public TikTok ad examples and compare messaging over time. **Researchers** can collect public ad records by country, advertiser, and keyword with direct detail links for review. ### What input does TikTok Ads Library Scraper accept? ```json { "targets": ["Nike", "ASOS"], "country": "FR", "maxAds": 40, "shownSince": "2026-07-01" } ```` | Input | Required | Description | |---|---:|---| | `targets` | Yes | Advertiser names or keywords. Examples: `Nike`, `ASOS`, `running shoes`. | | `country` | Yes | Supported European Ads Library country. Examples: `FR`, `GB`, `DE`, `PT`. Default: `GB`. | | `maxAds` | No | Maximum creatives to return per target. Default: `40`; maximum: `1000`. | | `shownSince` | No | Keep ads last shown on or after this `YYYY-MM-DD` date. Leave empty to use the default recent window. | | `firstShownAfter` | No | Keep ads first shown on or after this `YYYY-MM-DD` date. Leave empty to keep all returned first-shown dates. | | `queryType` | No | Use `auto` for advertiser and keyword matching, or `keyword` to force keyword-style search. | | `datasetId` | No | Existing Apify dataset ID for pipeline runs. Rows are appended there in addition to the default run dataset. | | `runId` | No | External workflow ID copied to output rows and `RUN_SUMMARY`. | ### What output does TikTok Ads Library Scraper return? Example row: ```json { "target": "Nike", "country": "FR", "countryName": "France", "adId": "1870539218886770", "advertiserName": "NIKE Retail B.V.", "firstShownDate": "2026-07-12", "lastShownDate": "2026-07-14", "title": "Commande l'equipement qui t'aidera a relever tous les defis.", "callToAction": "Shop now", "creativeText": "Commande l'equipement qui t'aidera a relever tous les defis. | Shop now", "estimatedAudience": "10K-100K", "creativeFormat": "video", "mediaAvailability": "video_url_exposed", "videoUrl": "https://library.tiktok.com/api/v1/cdn/...", "videoUrls": ["https://library.tiktok.com/api/v1/cdn/..."], "coverImageUrl": "https://p16-common-sign.tiktokcdn.com/...", "imageUrls": ["https://p16-common-sign.tiktokcdn.com/..."], "adDetailsUrl": "https://library.tiktok.com/ads/detail/?ad_id=1870539218886770®ion=FR" } ``` `creativeFormat` is inferred from the media URLs exposed in the public search record: - `video` means `videoUrl` or `videoUrls` was exposed. - `image_or_carousel` means no video URL was exposed, but `coverImageUrl` or `imageUrls` was exposed. - `media_not_exposed` means TikTok returned the ad record and copy but did not expose a media URL in the search payload. `mediaAvailability` provides the matching extraction status: `video_url_exposed`, `image_url_exposed`, or `no_media_url_exposed`. The actor intentionally focuses on the fast public search data, so it does not depend on TikTok's unstable ad-detail endpoint for landing pages, sponsor profiles, or targeting breakdowns. ### How do I run TikTok Ads Library Scraper? 1. Add one or more advertiser names or keywords. 2. Choose a supported country. 3. Set `maxAds` based on how deep you want the run to go. 4. Optionally add date filters for monitoring new or recently shown ads. 5. Run the actor and download the dataset as JSON, CSV, Excel, or through the Apify API. ### How can I use TikTok Ads Library Scraper through the API? ```bash curl "https://api.apify.com/v2/acts/YOUR_USERNAME~tiktok-ads-library-scraper/runs" \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $APIFY_TOKEN" \ -d '{ "targets": ["Nike"], "country": "FR", "maxAds": 40 }' ``` Fetch dataset items: ```bash curl "https://api.apify.com/v2/datasets/DATASET_ID/items?clean=true" \ -H "Authorization: Bearer $APIFY_TOKEN" ``` ### How can I monitor advertisers over time? Schedule the actor daily or weekly with the same targets and country. Use `adId`, `firstShownDate`, and `lastShownDate` to detect fresh, recurring, or recently stopped creatives. ### What are the limits of TikTok Ads Library Scraper? - The public TikTok Ads Library path tested here is focused on supported European countries. - It does not claim complete global TikTok ad coverage. - Some public records expose text but no media URL. These rows are labeled with `creativeFormat: "media_not_exposed"` and `mediaAvailability: "no_media_url_exposed"`. - `creativeFormat` is an inference from exposed media URLs, not TikTok's private campaign setup field. - Landing pages, sponsor profile details, and targeting breakdowns are not included because TikTok's public detail endpoint is unstable at scale. - TikTok can change internal public endpoints or payload shapes. The actor records failures in `RUN_SUMMARY` rather than inventing rows. ### How do I troubleshoot TikTok Ads Library Scraper? | Issue | Likely cause | Solution | |---|---|---| | No rows were returned | The advertiser has no public ads in that country, or date filters removed all rows | Try another supported country, broaden the target, or remove date filters. | | The result matched a related advertiser | Broad keywords can match agencies, retailers, or product mentions | Use a more specific brand name or switch `queryType` to `keyword` when you want keyword matching. | | Some rows do not have videos | The public search record exposed image media only, or exposed no media URL | Check `creativeFormat`, `mediaAvailability`, `coverImageUrl`, `imageUrls`, and the public `adDetailsUrl`. | | A run is slower for some targets | The target has duplicate or sparse result pages | Lower `maxAds` for quick checks or split large target lists across runs. | ### What changed in the current version? #### 0.1 - Initial version with public search, ad dates, ad copy, media format labels, video/cover assets, audience ranges, and pipeline fields. ### How can I get support? Open an issue on the actor page with the target, country, run ID, and a short description of what looked wrong. Include whether the problem was matching, missing rows, date filtering, or media extraction. # Actor input Schema ## `targets` (type: `array`): Advertiser names or keywords to search. Examples: Nike, ASOS, running shoes. Exact advertiser suggestions are resolved internally when available. ## `country` (type: `string`): Country whose public TikTok Ads Library results should be checked. TikTok currently exposes this public library for supported European countries. Default: GB. ## `maxAds` (type: `integer`): Maximum number of ad creatives to return per target. Use 5-50 for quick checks and higher values for deeper monitoring. Default: 40; maximum: 1000. ## `shownSince` (type: `string`): Only keep ads last shown on or after this date. Use YYYY-MM-DD, for example 2026-07-01. Leave empty to use the actor's default recent date window. ## `firstShownAfter` (type: `string`): Only keep ads first shown on or after this date. Use YYYY-MM-DD, for example 2026-01-01. Leave empty to keep all returned first-shown dates. ## `queryType` (type: `string`): Choose how targets are interpreted. Auto uses TikTok's advertiser and keyword matching. Keyword searches ad text and creative metadata. Default: auto. ## `datasetId` (type: `string`): Optional existing Apify dataset ID for pipeline runs. When provided, rows are appended there in addition to the default run dataset. Leave empty for normal one-off runs. ## `runId` (type: `string`): Optional external run or workflow ID to include in output rows and RUN\_SUMMARY. Use it to join scheduled runs with your own monitoring jobs; leave empty when not needed. ## Actor input object example ```json { "targets": [ "Nike" ], "country": "GB", "maxAds": 40, "queryType": "auto" } ``` # Actor output Schema ## `datasetUrl` (type: `string`): No description ## `runSummaryUrl` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "targets": [ "Nike" ] }; // Run the Actor and wait for it to finish const run = await client.actor("trovevault/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 = { "targets": ["Nike"] } # Run the Actor and wait for it to finish run = client.actor("trovevault/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 '{ "targets": [ "Nike" ] }' | apify call trovevault/tiktok-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=trovevault/tiktok-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper", "description": "Extract public TikTok ad creatives with advertiser names, ad IDs, dates, ad text, audience ranges, media URLs, and media-based creative format labels.", "version": "0.1", "x-build-id": "1rMXq09aMU5E9n7Y3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/trovevault~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-trovevault-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/trovevault~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-trovevault-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/trovevault~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-trovevault-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", "required": [ "targets", "country" ], "properties": { "targets": { "title": "Advertisers or Keywords", "type": "array", "description": "Advertiser names or keywords to search. Examples: Nike, ASOS, running shoes. Exact advertiser suggestions are resolved internally when available.", "items": { "type": "string" }, "default": [ "Nike" ] }, "country": { "title": "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" ], "type": "string", "description": "Country whose public TikTok Ads Library results should be checked. TikTok currently exposes this public library for supported European countries. Default: GB.", "default": "GB" }, "maxAds": { "title": "Maximum Ads", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of ad creatives to return per target. Use 5-50 for quick checks and higher values for deeper monitoring. Default: 40; maximum: 1000.", "default": 40 }, "shownSince": { "title": "Shown Since", "type": "string", "description": "Only keep ads last shown on or after this date. Use YYYY-MM-DD, for example 2026-07-01. Leave empty to use the actor's default recent date window." }, "firstShownAfter": { "title": "First Shown After", "type": "string", "description": "Only keep ads first shown on or after this date. Use YYYY-MM-DD, for example 2026-01-01. Leave empty to keep all returned first-shown dates." }, "queryType": { "title": "Search Type", "enum": [ "auto", "keyword" ], "type": "string", "description": "Choose how targets are interpreted. Auto uses TikTok's advertiser and keyword matching. Keyword searches ad text and creative metadata. Default: auto.", "default": "auto" }, "datasetId": { "title": "Dataset ID", "type": "string", "description": "Optional existing Apify dataset ID for pipeline runs. When provided, rows are appended there in addition to the default run dataset. Leave empty for normal one-off runs." }, "runId": { "title": "Run ID", "type": "string", "description": "Optional external run or workflow ID to include in output rows and RUN_SUMMARY. Use it to join scheduled runs with your own monitoring jobs; leave empty when not needed." } } }, "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 } } } } } } } } } } ```