# TikTok Top Ads Scraper (`lexis-solutions/tiktok-top-ads-scraper`) Actor TikTok Top Ads scraper to extract Creative Center Top Ads metadata, videos, engagement metrics, CTR/CVR, and landing pages for ad research, competitor analysis, and TikTok ads intelligence dashboards and datasets. - **URL**: https://apify.com/lexis-solutions/tiktok-top-ads-scraper.md - **Developed by:** [Lexis Solutions](https://apify.com/lexis-solutions) (community) - **Categories:** Social media, AI, Videos - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.49 / 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 Top Ads Scraper ![banner](https://i.imgur.com/O9e9j57.png) TikTok Creative Center Top Ads is a public ad inspiration library. This actor collects structured Top Ads data, video metadata, engagement fields, landing pages, and keyframe performance metrics from TikTok Creative Center. ### Introduction The TikTok Top Ads scraper starts from Creative Center Top Ads URLs, ad detail URLs, or a keyword input. It follows Top Ads result pages, opens each ad record, and extracts structured data for research and analytics workflows. ### Use Cases - **Creative research**: Analyze ad titles, brands, landing pages, hooks, video metadata, and visible ad patterns. - **Competitor monitoring**: Track Top Ads across selected countries, industries, objectives, and time periods. - **Performance analysis**: Collect available retention, click, conversion, and play-retention keyframe metrics. - **Data pipelines**: Feed dashboards, spreadsheets, BI tools, and internal ad intelligence workflows. ### Input Provide the following fields: - `startUrls` (array, optional): TikTok Creative Center Top Ads list URLs or Top Ads detail URLs. - `keyword` (string, optional): Keyword used to search Top Ads results. - `country` (array, optional): One or more country filters. - `industry` (array, optional): One or more industry filters. - `objective` (array, optional): One or more campaign objective filters. - `adLanguage` (array, optional): One or more ad language filters. - `adFormat` (string, optional): Ad format filter. Select Spark Ads or Non-Spark Ads. - `orderBy` (string, optional): Result order. Supports For You, CTR, Reach, 2 Views Rate, 6 Views Rate, CVR, and Likes. - `period` (string, optional): Top Ads time range. Supported values are Last 7 days, Last 30 days, and Last 180 days. - `maxItems` (integer, optional): Maximum number of ad items to extract per source. - `proxyConfiguration` (object, optional): Apify proxy settings. Notes: - Provide at least one of `startUrls` or `keyword`. - A keyword can be used with `startUrls`, or by itself when no start URL is provided. - Country, industry, objective, ad language, ad format, order, and period filters are applied to list requests. - Crawling stops per source when `maxItems` is reached or when no more Top Ads results are available. - Proxies are recommended for stable larger runs. ### Input Examples **1) Start URLs** ```json { "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30®ion=ID" } ], "maxItems": 20, "proxyConfiguration": { "useApifyProxy": true } } ```` **2) Keyword with filters** ```json { "keyword": "kaos", "country": ["ID"], "industry": ["22"], "objective": ["3"], "adLanguage": ["id", "en"], "adFormat": "1", "orderBy": "impression", "period": "180", "maxItems": 20, "proxyConfiguration": { "useApifyProxy": true } } ``` ### Output Each dataset item contains fields like: ```json { "id": "7638635028650033160", "title": "18 bayi terlantar menangis lapar. Mari bantu penuhi stok susu & popok mereka.", "brandName": "", "countryCodes": ["ID"], "landingPage": "https://example.com/campaign", "source": "TikTok Ads Manager", "sourceKey": 1, "industryKey": "label_23105000000", "objectiveKey": "campaign_objective_conversion", "objectives": [ { "label": "campaign_objective_conversion", "value": 3 } ], "ctr": 0.5, "cost": 1, "likes": 360, "comments": 7, "shares": 4, "favorite": false, "keywords": [], "patternLabels": [], "highlightText": "", "hasSummary": false, "voiceOver": false, "videoId": "v10033g50000d81e9hvog65iv8kn62pg", "videoDuration": 41.2, "videoCover": "https://example.com/video-cover", "videoUrls": { "720p": "https://example.com/video-720p" }, "videoWidth": 720, "videoHeight": 1280, "retainCvr": { "duration": 42, "highlights": [13, 15, 38], "analysis": [ { "second": 0, "value": 0 } ] }, "retainCtr": { "duration": 42, "highlights": [13, 20, 38], "analysis": [] }, "clickCount": { "duration": 42, "highlights": [1, 3, 13], "analysis": [] }, "conversionCount": { "duration": 42, "highlights": [2, 13, 15], "analysis": [] }, "playRetainCount": { "duration": 42, "highlights": [], "analysis": [] } } ``` The scraper paginates through Top Ads list results and enriches each ad with available detail and keyframe metric data. ### Why use the TikTok Top Ads Scraper? - **Focused**: Built for TikTok Creative Center Top Ads list and detail flows. - **Filtered searches**: Supports keyword, country, industry, objective, ad language, ad format, order, and period inputs. - **Structured output**: Produces ready-to-use JSON records for ad research and automation. - **Metric enrichment**: Includes available retention, click, conversion, and play-retention keyframe data. - **Apify-native**: Works with Apify datasets, request queues, and proxy configuration. ### FAQ - **How many ads can it extract?**\ Controlled by `maxItems` per source list. - **Can I scrape one ad detail page?**\ Yes. Add a Top Ads detail URL to `startUrls`. - **Can I search without a start URL?**\ Yes. Provide `keyword` and optional filters. - **Do I need proxies?**\ Proxies are recommended for stability, especially for larger runs. - **What if some metric fields are empty?**\ The actor keeps the ad record and returns available data when a keyframe metric is not available. - **What if TikTok Creative Center changes?**\ The actor may require updates to keep extraction stable. ### Need to scrape ads from other platforms? Check out our other scrapers: - [TikTok Ads](https://apify.com/lexis-solutions/tiktok-ads-scraper). - [Google Ads](https://apify.com/lexis-solutions/google-ads-scraper). - [Bing Ads](https://apify.com/lexis-solutions/bing-ads-scraper). - [Reddit Ads](https://apify.com/lexis-solutions/reddit-ads-scraper). *** **Need help or want a custom solution?** Lexis Solutions is a certified Apify Partner. We can help with custom data extraction projects. Contact us over [Email](mailto:scraping@lexis.solutions) or [LinkedIn](https://www.linkedin.com/company/lexis-solutions). ### Support Our Work If you're happy with our work and scrapers, you're welcome to leave us a company review [here](https://apify.com/partners/find/lexis-solutions/review) and leave a review for the scrapers you're subscribed to. ### Image Credit Image credit: [TikTok Creative Center](https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en) # Actor input Schema ## `startUrls` (type: `array`): TikTok Creative Center Top Ads URLs to scrape. ## `keyword` (type: `string`): Search Top Ads by keyword. ## `country` (type: `array`): Select one or more countries to apply to the Top Ads URLs. ## `industry` (type: `array`): Select one or more industries. ## `objective` (type: `array`): Select one or more campaign objectives. ## `adLanguage` (type: `array`): Select one or more ad languages. ## `adFormat` (type: `string`): Select the ad format. ## `orderBy` (type: `string`): Select how Top Ads results are ordered. ## `period` (type: `string`): Select the Top Ads time period. ## `maxItems` (type: `integer`): Maximum number of items per original URL. ## `proxyConfiguration` (type: `object`): Your proxy configuration from Apify. ## Actor input object example ```json { "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30" } ], "orderBy": "for_you", "period": "30", "maxItems": 5, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `overview` (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 = { "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("lexis-solutions/tiktok-top-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30" }] } # Run the Actor and wait for it to finish run = client.actor("lexis-solutions/tiktok-top-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 '{ "startUrls": [ { "url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?period=30" } ] }' | apify call lexis-solutions/tiktok-top-ads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lexis-solutions/tiktok-top-ads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Scraper", "description": "TikTok Top Ads scraper to extract Creative Center Top Ads metadata, videos, engagement metrics, CTR/CVR, and landing pages for ad research, competitor analysis, and TikTok ads intelligence dashboards and datasets.", "version": "1.0", "x-build-id": "ZVsQ3Q8TOsDnzoC3u" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lexis-solutions~tiktok-top-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lexis-solutions-tiktok-top-ads-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/lexis-solutions~tiktok-top-ads-scraper/runs": { "post": { "operationId": "runs-sync-lexis-solutions-tiktok-top-ads-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/lexis-solutions~tiktok-top-ads-scraper/run-sync": { "post": { "operationId": "run-sync-lexis-solutions-tiktok-top-ads-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": [ "maxItems" ], "properties": { "startUrls": { "title": "Start URLs", "type": "array", "description": "TikTok Creative Center Top Ads URLs to scrape.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "keyword": { "title": "Keyword", "type": "string", "description": "Search Top Ads by keyword." }, "country": { "title": "Countries", "type": "array", "description": "Select one or more countries to apply to the Top Ads URLs.", "items": { "type": "string", "enum": [ "DZ", "AR", "AU", "AT", "AZ", "BH", "BD", "BY", "BE", "BO", "BR", "BG", "KH", "CA", "CL", "CO", "CR", "HR", "CY", "CZ", "DK", "DO", "EC", "EG", "EE", "FI", "FR", "DE", "GR", "GT", "JO", "HU", "ID", "IQ", "IE", "IL", "IT", "JP", "KZ", "KE", "KW", "LV", "LB", "MY", "MX", "MA", "NL", "NZ", "NG", "NO", "OM", "PK", "PA", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "LT", "RO", "SA", "RS", "SG", "SK", "SI", "ZA", "KR", "ES", "LK", "SE", "CH", "TW", "TH", "TR", "AE", "GB", "US", "UY", "VN" ], "enumTitles": [ "Algeria", "Argentina", "Australia", "Austria", "Azerbaijan", "Bahrain", "Bangladesh", "Belarus", "Belgium", "Bolivia", "Brazil", "Bulgaria", "Cambodia", "Canada", "Chile", "Colombia", "Costa Rica", "Croatia", "Cyprus", "Czechia", "Denmark", "Dominican Republic", "Ecuador", "Egypt", "Estonia", "Finland", "France", "Germany", "Greece", "Guatemala", "Hashemite Kingdom of Jordan", "Hungary", "Indonesia", "Iraq", "Ireland", "Israel", "Italy", "Japan", "Kazakhstan", "Kenya", "Kuwait", "Latvia", "Lebanon", "Malaysia", "Mexico", "Morocco", "Netherlands", "New Zealand", "Nigeria", "Norway", "Oman", "Pakistan", "Panama", "Paraguay", "Peru", "Philippines", "Poland", "Portugal", "Puerto Rico", "Qatar", "Republic of Lithuania", "Romania", "Saudi Arabia", "Serbia", "Singapore", "Slovakia", "Slovenia", "South Africa", "South Korea", "Spain", "Sri Lanka", "Sweden", "Switzerland", "Taiwan", "Thailand", "Turkey", "United Arab Emirates", "United Kingdom", "United States", "Uruguay", "Vietnam" ] } }, "industry": { "title": "Industries", "type": "array", "description": "Select one or more industries.", "items": { "type": "string", "enum": [ "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30" ], "enumTitles": [ "Education", "Vehicle & Transportation", "Baby, Kids & Maternity", "Financial Services", "Beauty & Personal Care", "Tech & Electronics", "Appliances", "Travel", "Household Products", "Pets", "Apps", "Home Improvement", "Apparel & Accessories", "News & Entertainment", "Business Services", "Games", "Life Services", "Food & Beverage", "Sports & Outdoor", "Health", "E-Commerce (Non-app)" ] } }, "objective": { "title": "Objectives", "type": "array", "description": "Select one or more campaign objectives.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "8", "15" ], "enumTitles": [ "Traffic", "App Installs", "Conversions", "Video Views", "Reach", "Lead Generation", "Product sales" ] } }, "adLanguage": { "title": "Ad Languages", "type": "array", "description": "Select one or more ad languages.", "items": { "type": "string", "enum": [ "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko" ], "enumTitles": [ "English", "Spanish", "Arabic", "Vietnamese", "Thai", "German", "Indonesian", "Portuguese", "French", "Malay", "Dutch", "Japanese", "Italian", "Romanian", "Traditional Chinese", "Korean" ] } }, "adFormat": { "title": "Ad Format", "enum": [ "1", "2" ], "type": "string", "description": "Select the ad format." }, "orderBy": { "title": "Order By", "enum": [ "ctr", "for_you", "impression", "play_2s_rate", "play_6s_rate", "cvr", "like" ], "type": "string", "description": "Select how Top Ads results are ordered.", "default": "for_you" }, "period": { "title": "Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Select the Top Ads time period.", "default": "30" }, "maxItems": { "title": "Maximum number of items", "type": "integer", "description": "Maximum number of items per original URL.", "default": 5 }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Your proxy configuration from Apify.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```