# TikTok Ads Library Scraper (`fetch_cat/tiktok-ads-library-scraper`) Actor Scrape public TikTok Creative Center Top Ads by keyword, region, period, language, objective, and industry. Export ad text, media, metrics, and URLs. - **URL**: https://apify.com/fetch\_cat/tiktok-ads-library-scraper.md - **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community) - **Categories:** Social media, Marketing - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.11 / 1,000 ad records 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 Creative Center Top Ads into a clean dataset for competitive ad research, creative inspiration, and campaign monitoring. ### What does TikTok Ads Library Scraper do? TikTok Ads Library Scraper collects public ad creative records from TikTok Creative Center Top Ads. It helps you turn visible TikTok ad examples into structured data. You can search by keyword. You can select markets such as `US`, `GB`, `DE`, `FR`, `BR`, `JP`, or `AU`. You can choose a time period. You can limit the number of ads saved. Each result includes ad text, identifiers, creative media links, filter context, and public performance labels when TikTok provides them. ### Who is it for? Performance marketers use it to watch competitor creatives. Ecommerce brands use it to discover hooks and offers that are working on TikTok. Agencies use it to prepare creative research decks. Growth teams use it to monitor ad trends in target regions. Researchers use it to analyze public advertising patterns. Founders use it to quickly understand how similar products are promoted. ### Why use this actor? 🧠 Find creative angles faster. πŸ“Š Export TikTok ad examples to spreadsheets or BI tools. 🌎 Compare ads across markets. πŸ”Ž Search by brand, product, or topic keywords. ⏱️ Save manual browsing time. 🧩 Combine TikTok ad intelligence with your own campaign notes. ### What data can it extract? | Field | Description | | --- | --- | | `adId` | TikTok Creative Center ad identifier | | `detailUrl` | Public Creative Center detail URL | | `brandName` | Brand name when available | | `advertiserName` | Advertiser name when available | | `adText` | Public ad title or caption text | | `landingPageUrl` | Landing page URL when available | | `videoUrl` | Public creative video URL when available | | `coverImageUrl` | Creative thumbnail image | | `durationSeconds` | Video duration | | `likes` | Public like count label when available | | `ctr` | Public CTR metric when available | | `costIndex` | Public cost index when available | | `industryKey` | TikTok industry key | | `objectiveKey` | TikTok objective key | | `countryCode` | Market used for the search | | `keyword` | Keyword used for the search | | `scrapedAt` | Timestamp of extraction | ### How much does it cost to scrape TikTok ads? The actor uses pay-per-event pricing. There is a small start event for each run. There is a per-result event for each ad record saved. For a small research run, set `maxItems` to 20. For broader monitoring, increase `maxItems` after you confirm the filters return useful data. Exact pricing is shown on the Apify actor page before you start a run. ### How to scrape TikTok ads 1. Open the actor on Apify. 2. Enter one or more keywords, for example `skincare`, `game`, or `running shoes`. 3. Add one or more region codes, for example `US`. 4. Choose a period such as the last 7 or 30 days. 5. Set `maxItems`. 6. Start the run. 7. Export the dataset as JSON, CSV, Excel, XML, RSS, or HTML. ### Input configuration #### `keywords` Optional keyword searches. Leave empty to collect general top ads for the selected region. #### `regions` Country codes used by TikTok Creative Center. Examples: `US`, `GB`, `DE`, `FR`, `BR`, `JP`, `AU`. #### `period` Supported values are 7, 30, 120, and 180 days. #### `maxItems` Global maximum number of ads saved. Use a small value for the first run. #### `languages` Optional language filters such as `en`, `es`, `de`, `fr`, `pt`, or `ja`. #### `industries` and `objectives` Optional TikTok Creative Center filter keys. Leave empty unless you already know the keys you need. ### Example input ```json { "keywords": [], "regions": ["US"], "period": "7", "sortBy": "for_you", "maxItems": 20 } ```` ### Example output ```json { "adId": "7652301642913873941", "detailUrl": "https://ads.tiktok.com/business/creativecenter/topads/7652301642913873941", "brandName": null, "adText": "Example public TikTok ad text...", "videoUrl": "https://...", "coverImageUrl": "https://...", "likes": 1779, "ctr": 0.43, "countryCode": "US", "keyword": "coffee", "periodDays": 7, "scrapedAt": "2026-06-27T00:00:00.000Z" } ``` ### Tips for better results Start with one country and one keyword. Use short product category keywords. Try both branded and generic searches. Compare periods to see whether creatives are recent or persistent. If a keyword returns few ads, broaden the term. If you need trend monitoring, schedule the actor to run weekly. ### Integrations Send results to Google Sheets for creative review. Export CSV for media buying analysis. Connect datasets to Make or Zapier for alerts. Use Apify webhooks to notify your team when a scheduled run finishes. Store historical datasets to compare creative changes over time. Join results with your own product taxonomy in a warehouse. ### API usage #### Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('fetch_cat/tiktok-ads-library-scraper').call({ keywords: [], regions: ['US'], period: '7', maxItems: 20 }); console.log(run.defaultDatasetId); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('MY-APIFY-TOKEN') run = client.actor('fetch_cat/tiktok-ads-library-scraper').call(run_input={ 'keywords': [], 'regions': ['US'], 'period': '7', 'maxItems': 20, }) print(run['defaultDatasetId']) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/fetch_cat~tiktok-ads-library-scraper/runs?token=MY-APIFY-TOKEN' \ -H 'Content-Type: application/json' \ -d '{"keywords":[],"regions":["US"],"period":"7","maxItems":20}' ``` ### MCP usage Use TikTok Ads Library Scraper as an AI-agent tool through Apify MCP. This lets Claude Code, Claude Desktop, and other MCP-compatible clients run the actor, pass structured inputs, and return the dataset ID for follow-up analysis in your agent workflow. MCP URL: ```text https://mcp.apify.com/?tools=fetch_cat/tiktok-ads-library-scraper ``` #### Claude Code setup ```bash claude mcp add apify-tiktok-ads "https://mcp.apify.com/?tools=fetch_cat/tiktok-ads-library-scraper" ``` #### Claude Desktop setup Add this server to your Claude Desktop MCP configuration: ```json { "mcpServers": { "apify-tiktok-ads": { "url": "https://mcp.apify.com/?tools=fetch_cat/tiktok-ads-library-scraper" } } } ``` After connecting the MCP server, ask your assistant to run the TikTok Ads Library Scraper with your target market, keyword, and item limit. Example prompts showing MCP usage are included in the AI agent usage section below. ### AI agent usage AI agents can use this actor to collect competitor ad examples, summarize creative hooks, and prepare ad-intelligence briefs without manual Creative Center browsing. Keep prompts specific about market, keyword, period, and maximum result count so the agent can choose safe inputs. Example prompts: - β€œFind 20 public TikTok top ads in the US for skincare and summarize the most common hooks.” - β€œCompare public TikTok ad creatives for running shoes in the US and GB over the last 30 days. Group results by offer angle.” - β€œRun a weekly competitor-ad scan for coffee brands in the US, export the dataset, and highlight landing pages that appear repeatedly.” ### Scheduling Schedule the actor weekly to monitor new creatives. Use separate schedules per market if you track many countries. Keep `maxItems` practical for routine monitoring. ### Troubleshooting If you receive no results, try a broader keyword. If a region returns no results, verify the country code. If TikTok temporarily limits public access, retry later with a smaller run. If you need exact industry keys, first run without industry filters. ### Limits The actor only extracts public Creative Center data. It does not log in to TikTok. It does not access private advertiser accounts. Availability can vary by market, keyword, and TikTok's public interface. Video URLs may expire because they are served by TikTok's media infrastructure. ### Legality and ethical use This actor is intended for public data research. Respect TikTok's terms and applicable laws. Do not use results for spam, harassment, or deceptive advertising. Do not attempt to identify private users from aggregate ad information. ### Related scrapers - [Google Ads Transparency Scraper](https://apify.com/fetch_cat/google-ads-transparency-scraper) - [TikTok Profile Scraper](https://apify.com/fetch_cat/tiktok-profile-scraper) - [TikTok Hashtag Scraper](https://apify.com/fetch_cat/tiktok-hashtag-scraper) ### FAQ #### Can I scrape TikTok ads without logging in? Yes. This actor is designed for public Creative Center data and does not require user credentials. #### Can I filter by country? Yes. Use `regions` with country codes such as `US`, `GB`, or `DE`. #### Can I get the video creative? When TikTok provides a public video URL, the actor saves it as `videoUrl`. #### Why is `brandName` sometimes empty? Some public ad records do not include a brand label. #### Can I monitor competitors over time? Yes. Create a schedule and store each dataset for historical comparison. #### Does it scrape private ads? No. It only handles public data visible through TikTok Creative Center. ### Changelog Initial version extracts public Top Ads records with keywords, region filters, media URLs, and public performance labels. # Actor input Schema ## `keywords` (type: `array`): Optional ad text or brand keywords to search. Leave empty to return top ads for the selected markets. ## `regions` (type: `array`): TikTok Creative Center country codes such as US, GB, DE, FR, BR, JP, AU. Use one or a few for focused runs. ## `maxItems` (type: `integer`): Maximum number of ad records to save across all keyword and region combinations. ## `period` (type: `string`): Lookback window used by TikTok Creative Center. ## `industries` (type: `array`): Optional TikTok industry/category keys. Leave empty for all industries. ## `objectives` (type: `array`): Optional campaign objective keys. Leave empty for all objectives. ## `languages` (type: `array`): Optional language codes such as en, es, de, fr, pt, ja. Leave empty for all languages. ## `adFormat` (type: `string`): Optional TikTok ad format key if you want to narrow results. ## `sortBy` (type: `string`): Ranking used by TikTok Creative Center. ## `startUrls` (type: `array`): Optional TikTok Creative Center Top Ads URLs. Query parameters like keyword, countryCode, and period are used as hints. ## Actor input object example ```json { "keywords": [], "regions": [ "US" ], "maxItems": 20, "period": "7", "sortBy": "for_you", "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?countryCode=US&period=7" } ] } ``` # Actor output Schema ## `ads` (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 = { "keywords": [], "regions": [ "US" ], "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?countryCode=US&period=7" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("fetch_cat/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 = { "keywords": [], "regions": ["US"], "startUrls": [{ "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?countryCode=US&period=7" }], } # Run the Actor and wait for it to finish run = client.actor("fetch_cat/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 '{ "keywords": [], "regions": [ "US" ], "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?countryCode=US&period=7" } ] }' | apify call fetch_cat/tiktok-ads-library-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=fetch_cat/tiktok-ads-library-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper", "description": "Scrape public TikTok Creative Center Top Ads by keyword, region, period, language, objective, and industry. Export ad text, media, metrics, and URLs.", "version": "0.1", "x-build-id": "BGuTWTkjjLZhGqfqu" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetch_cat~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetch_cat-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/fetch_cat~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-fetch_cat-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/fetch_cat~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-fetch_cat-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": { "keywords": { "title": "Keywords", "type": "array", "description": "Optional ad text or brand keywords to search. Leave empty to return top ads for the selected markets.", "items": { "type": "string" } }, "regions": { "title": "Regions / country codes", "type": "array", "description": "TikTok Creative Center country codes such as US, GB, DE, FR, BR, JP, AU. Use one or a few for focused runs.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of ad records to save across all keyword and region combinations.", "default": 20 }, "period": { "title": "Time period", "enum": [ "7", "30", "120", "180" ], "type": "string", "description": "Lookback window used by TikTok Creative Center.", "default": "7" }, "industries": { "title": "Industry keys", "type": "array", "description": "Optional TikTok industry/category keys. Leave empty for all industries.", "items": { "type": "string" } }, "objectives": { "title": "Objective keys", "type": "array", "description": "Optional campaign objective keys. Leave empty for all objectives.", "items": { "type": "string" } }, "languages": { "title": "Ad languages", "type": "array", "description": "Optional language codes such as en, es, de, fr, pt, ja. Leave empty for all languages.", "items": { "type": "string" } }, "adFormat": { "title": "Ad format", "type": "string", "description": "Optional TikTok ad format key if you want to narrow results." }, "sortBy": { "title": "Sort by", "enum": [ "for_you", "ctr", "like", "cost" ], "type": "string", "description": "Ranking used by TikTok Creative Center.", "default": "for_you" }, "startUrls": { "title": "Creative Center URLs", "type": "array", "description": "Optional TikTok Creative Center Top Ads URLs. Query parameters like keyword, countryCode, and period are used as hints.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } } } }, "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 } } } } } } } } } } ```