# TikTok Ads Spy (`lurkapi/tiktok-ads-spy`) Actor Scrape ads from TikTok Ads Library (EU/EEA + UK + Switzerland + Turkey) and Creative Center Top Ads (global, includes US). Filter by region, advertiser, date range, industry, objective. Optional video download and landing-page resolution. - **URL**: https://apify.com/lurkapi/tiktok-ads-spy.md - **Developed by:** [LurkAPI](https://apify.com/lurkapi) (community) - **Categories:** Automation, E-commerce, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 ad scrapeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## TikTok Ads Spy See what advertisers are running on TikTok. This tool collects real ads from TikTok's two public ad libraries and gives you back a clean spreadsheet of advertiser names, ad copy, video files, dates, engagement numbers, and where each ad sends viewers when they click. Useful for: - Marketers studying competitor campaigns - Agencies pitching new clients with proof of what works - Journalists tracking political or commercial advertising - Researchers spotting trends - Anyone who wants to know what's working on TikTok right now ### 🎬 What you can scrape The tool pulls from two TikTok sources. Pick whichever matches what you need. #### Option 1: TikTok Ads Library TikTok's official ad transparency database, required by European law. Covers ads shown in these countries: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey, United Kingdom. Pick this if you want EU or UK ad data with detailed transparency information like audience size estimates, money spent, and how long the ad has been running. Important: TikTok does not publish a US Ads Library. If you need United States data, use the Creative Center option below. #### Option 2: TikTok Creative Center Top Ads TikTok's "inspiration board" of top performing ads. Covers nearly every country including the United States, with engagement numbers like click through rate, like counts, and multiple video quality options. Pick this if you want global or US data, or if you want to see what is performing best in your category right now. #### Quick comparison | | 🇪🇺 Ads Library | 🌍 Creative Center Top Ads | |---|---|---| | **Coverage** | 33 countries: EU/EEA, UK, Switzerland, Turkey | 81 countries worldwide, **includes the US** | | **What it shows** | Every ad an advertiser ran, by legal disclosure | Top-performing ads TikTok curates as inspiration | | **Ads per search** | ~80-100 max (TikTok ceiling) | Hundreds per filter slice | | **Performance data** | Impressions bucket, audience size estimate, days active | CTR, likes, comments, shares, days active | | **Spend / budget** | Real dollar range (e.g. "$10K-$50K") | Relative tier (Low / Medium / High) | | **Search by advertiser** | ✅ Yes — by name or business ID | ❌ No native filter (keyword in title only) | | **Look up specific ads by ID** | ✅ Yes | ❌ No | | **Filter by industry / objective / language** | ❌ No | ✅ Yes | | **Date range options** | Custom + presets up to 1 year | 7 / 30 / 180 days only | | **Sort options** | Most / oldest shown or launched | For You / CTR / Likes / play-rate | ### 📋 How to use it #### Step 1: Pick your source In the input form, choose either "Ads Library" or "Creative Center Top Ads." #### Step 2: Tell it what you want You have two ways to set up your search. Pick whichever is easiest. **A. Fill in the form fields (recommended).** The input form has dropdowns and text boxes for every filter TikTok lets you set on their own site. For Ads Library: Region, Keyword or advertiser name (with a 'Search by' toggle), Advertiser business IDs, Date range, Sort order. For Creative Center: Country, Period (7/30/180 days), Keyword, Campaign objective (Traffic, App Installs, Conversions, Video Views, Reach, Lead Generation, Product sales), Ad language, Industry, Sort order (For You, CTR, Likes, 6 second play rate, 25% play rate). Set whichever fields you care about. Leave the rest blank. **B. Look up specific ads by ID (Ads Library only).** Drop one or more numeric ad IDs into the "Ad IDs" field. Use "Skip ad IDs" for IDs you have already scraped, so you do not pay for them twice. If you leave everything empty and pick Creative Center, the tool runs a default search for the top US ads from the last 30 days. #### Step 3: Pick how many ads you want Set "Max ads per URL." The default is 50. Set it higher to get more. #### Step 4 (optional): Turn on extras There are three optional add ons. Each costs a small amount per item, and you only pay when it actually works. - **Enrich with ad details**: pulls extra fields on every row: call-to-action button text, advertising objective, destination URL, voiceover yes/no, comment and share counts, every country the ad ran in, campaign keywords, and more. $0.001 per ad enriched. - **Download video**: saves each ad's video file. $0.003 per video. - **Resolve landing page**: follows the ad's click link to find the actual page it sends viewers to. $0.001 per link. Ads Library only. #### Step 5: Click Start Results stream in as they arrive. You can download the full dataset as JSON, CSV, Excel, or HTML when the run finishes. ### 📦 What you get back Each ad becomes one row with these fields: - Ad ID and a clickable link back to the ad on TikTok - Advertiser or brand name - Ad copy (the text under the video) - Video URL and a thumbnail image - When the ad first ran and when it last ran (Ads Library) - Click through rate, like count, and cost tier (Creative Center) - Estimated audience size and money spent (Ads Library, when available) - Country or region the ad was shown in - Industry and campaign objective tags (Creative Center) - Final destination URL the ad sends viewers to (if you turn on landing page resolution) - Saved video file location (if you turn on video download) The Output tab gives you four ready made views to look at the data: - **Overview**: status, source, ad ID, advertiser, ad text, region, video link - **Media**: video links in every quality, thumbnail, dimensions, saved video file - **Stats**: first and last shown dates, days active, audience size, engagement metrics - **Landing pages**: tracker URL, final destination, call to action text, campaign objective ### 💰 Pricing You only pay for results. Failed runs cost nothing. | What you pay for | Price | What you get | |---|---|---| | Each ad in your results | $0.001 | One row of data per ad | | Ad details enrichment (optional) | $0.001 | Extra fields per ad: CTA, objective, destination URL, voiceover flag, counts, keywords | | Video file download (optional) | $0.003 | One MP4 video file saved to your storage | | Landing page resolution (optional) | $0.001 | The actual destination URL for one ad | Example total costs: - 100 ads, no extras: $0.10 - 100 ads with enrichment: $0.20 - 100 ads with video download: $0.40 - 100 ads with everything on: $0.60 ### ❓ Common questions **Why isn't the United States in the Ads Library?** The Ads Library is TikTok's compliance tool for European transparency law. There is no US version. For United States data, use the Creative Center source instead. **My run returned 0 ads. Why?** A few possible reasons: - The advertiser hasn't run ads in the country and date range you picked - Your keyword is too specific - TikTok sometimes slows requests when it sees a lot of activity. If that happens, wait a few minutes and try again. **Why did some videos fail to download?** TikTok signs video URLs with short expiration windows. If a download times out, the tool automatically tries a fresh URL. If it still fails, turn the video add on back on and re run. **Do I need to set up a proxy?** No. The tool handles all of that internally. There is no technical setup on your end. **Where do the video files go?** Into your Apify Key Value Store, which is just storage attached to the run. You can download files from there on the run page once the actor finishes. **Can I run this on a schedule?** Yes. Set up a schedule in Apify and the tool runs on its own. Use the "Skip ad IDs" field to avoid paying again for ads you already collected. **Can I scrape one specific advertiser?** Yes. For the Ads Library, copy the URL after you search for that advertiser, or use their business ID directly. For Creative Center, paste a URL filtered by industry or use the keyword search. **Why does the same Creative Center search return different ads each run?** TikTok's "For You" sort uses a personalization algorithm. If you want stable results, pick a different sort like CTR, Likes, or 6 second play rate. ### 💡 A few things to know - Country names in the Ads Library refer to where the ad was shown, not where the advertiser is based. - The Ads Library returns roughly 80 to 100 ads per search before TikTok stops showing more. To get bigger pulls, split your search into smaller date ranges and paste several URLs. - Video links from TikTok expire within hours. If you want to keep the videos, turn on the video download add on so the tool saves them while the link is still live. ### ⚖️ Legal This tool collects data that TikTok publishes itself in public places. The Ads Library is required by European transparency law. The Creative Center inspiration board is visible to anyone who visits the page. Use this tool for research, journalism, market analysis, ad monitoring, and learning. You are responsible for following TikTok's Terms of Service and the laws where you live. The developer is not responsible for misuse of the data. What information is available depends on TikTok at the time of the run. # Actor input Schema ## `source` (type: `string`): Which TikTok ad surface to scrape. Ads Library is TikTok's EU transparency database (EU/EEA + UK + Switzerland + Turkey only). Creative Center Top Ads is global and includes the US. ## `ccKeyword` (type: `array`): One or more search terms. Each runs as a separate search. Combined with Countries, you get one search per (keyword × country) pair. Matches ad title text. Outer quotes are stripped automatically. ## `ccCountry` (type: `array`): Pick one or more countries. The actor runs a separate search per country. Leave empty to default to United States. ## `ccPeriod` (type: `string`): Time window for the Top Ads list. ## `ccObjective` (type: `string`): Filter by the advertiser's campaign objective. ## `ccLanguage` (type: `string`): Filter by the language of the ad creative. ## `ccIndustry` (type: `string`): Filter Top Ads to a single industry. Pick a top-level category like 'Apparel & Accessories' to include every sub-industry below it, or pick a specific sub-industry to narrow further. ## `ccOrderBy` (type: `string`): How to order the Top Ads list. ## `alibQuery` (type: `array`): One or more search terms. Each runs as a separate search. Combined with Regions, you get one search per (keyword × region) pair. Outer quotes are stripped automatically (don't wrap terms in quotes unless you want TikTok's exact-match behavior, which usually returns 0 results). ## `alibQueryType` (type: `string`): What the search text matches against. ## `alibAdvBizIds` (type: `string`): Optional comma-separated TikTok business IDs to refine results when the advertiser name above matches several brands. Use together with the advertiser name and set 'Search by' to 'Advertiser name'. The business ID alone is ignored by TikTok. ## `alibRegion` (type: `array`): Pick one or more EU/EEA + UK + Switzerland + Turkey countries. The actor runs a separate search per country. Leave empty to default to United Kingdom. ## `alibPeriod` (type: `string`): Time window for the ad's last-shown date. Choose 'Custom' to enter explicit start and end dates below. ## `alibStartDate` (type: `string`): Only used when Date range is set to Custom. ISO date like 2025-01-15. ## `alibEndDate` (type: `string`): Only used when Date range is set to Custom. ISO date like 2025-12-31. ## `alibSortType` (type: `string`): How to order the Ads Library results. ## `alibAdIds` (type: `array`): Scrape specific Ads Library ads by ID. Each ID returns the full ad detail (advertiser name, dates, video URL, external link, call to action, advertising objective). One per line. ## `alibSkipAdIds` (type: `array`): Ad IDs already scraped in a previous run. The actor skips these before fetching, so you don't pay twice for the same ad. Useful for scheduled or incremental runs. ## `maxAds` (type: `integer`): Cap on ads returned per filter combination. Specific ad ID inputs always return one each, regardless of this cap. ## `outputVideoDownload` (type: `boolean`): Saves each ad's MP4 to your Apify key-value store. Adds savedVideoKey to the row. Billed at $0.003 per successful download. ## `outputLandingPage` (type: `boolean`): Follows the ad's click tracker URL to find the final merchant landing page. Ads Library only. Implies 'Fetch per-ad details' (the destination link is only on the detail endpoint). Billed at $0.001 per successful resolution. ## `outputFetchDetails` (type: `boolean`): Adds extra fields to every row: call-to-action button text, advertising objective, destination URL, voiceover yes/no, comment and share counts, every country the ad ran in, campaign keywords, and more. Useful for deeper competitor analysis and creative reviews. Billed at $0.001 per ad enriched. Only successful enrichments are charged. ## Actor input object example ```json { "source": "creativeCenter", "ccKeyword": [], "ccCountry": [], "ccPeriod": "30", "ccObjective": "", "ccLanguage": "", "ccIndustry": "", "ccOrderBy": "for_you", "alibQuery": [], "alibQueryType": "1", "alibRegion": [], "alibPeriod": "30", "alibSortType": "last_shown_date,desc", "alibAdIds": [], "alibSkipAdIds": [], "maxAds": 50, "outputVideoDownload": false, "outputLandingPage": false, "outputFetchDetails": false } ```` # Actor output Schema ## `overview` (type: `string`): At-a-glance view: status, advertiser, ad copy, country, dates, preview thumbnail. ## `creative` (type: `string`): The ad asset itself: video, images, copy, highlight, voiceover, dimensions. ## `campaign` (type: `string`): Funnel and intent: objective, CTA, tracker URL, final URL, industry, keywords, format patterns. ## `performance` (type: `string`): Engagement and spend metrics: CTR, likes, comments, shares, budget, audience, dates. ## `advertiser` (type: `string`): Who is running the ad: brand, paid-for-by sponsor, business IDs, registry, linked TikTok account. ## `keyValueStore` (type: `string`): Downloaded ad videos when the video-download add-on is enabled. # 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 = { "source": "creativeCenter", "ccKeyword": [], "ccCountry": [], "ccPeriod": "30", "ccObjective": "", "ccLanguage": "", "ccIndustry": "", "ccOrderBy": "for_you", "alibQuery": [], "alibQueryType": "1", "alibAdvBizIds": "", "alibRegion": [], "alibPeriod": "30", "alibStartDate": "", "alibEndDate": "", "alibSortType": "last_shown_date,desc", "alibAdIds": [], "alibSkipAdIds": [], "maxAds": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("lurkapi/tiktok-ads-spy").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 = { "source": "creativeCenter", "ccKeyword": [], "ccCountry": [], "ccPeriod": "30", "ccObjective": "", "ccLanguage": "", "ccIndustry": "", "ccOrderBy": "for_you", "alibQuery": [], "alibQueryType": "1", "alibAdvBizIds": "", "alibRegion": [], "alibPeriod": "30", "alibStartDate": "", "alibEndDate": "", "alibSortType": "last_shown_date,desc", "alibAdIds": [], "alibSkipAdIds": [], "maxAds": 50, } # Run the Actor and wait for it to finish run = client.actor("lurkapi/tiktok-ads-spy").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 '{ "source": "creativeCenter", "ccKeyword": [], "ccCountry": [], "ccPeriod": "30", "ccObjective": "", "ccLanguage": "", "ccIndustry": "", "ccOrderBy": "for_you", "alibQuery": [], "alibQueryType": "1", "alibAdvBizIds": "", "alibRegion": [], "alibPeriod": "30", "alibStartDate": "", "alibEndDate": "", "alibSortType": "last_shown_date,desc", "alibAdIds": [], "alibSkipAdIds": [], "maxAds": 50 }' | apify call lurkapi/tiktok-ads-spy --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lurkapi/tiktok-ads-spy", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Spy", "description": "Scrape ads from TikTok Ads Library (EU/EEA + UK + Switzerland + Turkey) and Creative Center Top Ads (global, includes US). Filter by region, advertiser, date range, industry, objective. Optional video download and landing-page resolution.", "version": "0.0", "x-build-id": "InyQeZlin5uAbMyQa" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~tiktok-ads-spy/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-tiktok-ads-spy", "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/lurkapi~tiktok-ads-spy/runs": { "post": { "operationId": "runs-sync-lurkapi-tiktok-ads-spy", "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/lurkapi~tiktok-ads-spy/run-sync": { "post": { "operationId": "run-sync-lurkapi-tiktok-ads-spy", "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": { "source": { "title": "Ad source", "enum": [ "adsLibrary", "creativeCenter" ], "type": "string", "description": "Which TikTok ad surface to scrape. Ads Library is TikTok's EU transparency database (EU/EEA + UK + Switzerland + Turkey only). Creative Center Top Ads is global and includes the US.", "default": "creativeCenter" }, "ccKeyword": { "title": "Keywords", "type": "array", "description": "One or more search terms. Each runs as a separate search. Combined with Countries, you get one search per (keyword × country) pair. Matches ad title text. Outer quotes are stripped automatically.", "items": { "type": "string" } }, "ccCountry": { "title": "Countries", "type": "array", "description": "Pick one or more countries. The actor runs a separate search per country. Leave empty to default to United States.", "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", "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", "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" ] } }, "ccPeriod": { "title": "Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window for the Top Ads list.", "default": "30" }, "ccObjective": { "title": "Campaign objective", "enum": [ "", "1", "2", "3", "4", "5", "8", "15" ], "type": "string", "description": "Filter by the advertiser's campaign objective.", "default": "" }, "ccLanguage": { "title": "Ad language", "enum": [ "", "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko" ], "type": "string", "description": "Filter by the language of the ad creative.", "default": "" }, "ccIndustry": { "title": "Industry", "enum": [ "", "22000000000", "22102000000", "22101000000", "22107000000", "22108000000", "22109000000", "22106000000", "22999000000", "22112000000", "22105000000", "22113000000", "22110000000", "22111000000", "16000000000", "16105000000", "16104000000", "16101000000", "16102000000", "16999000000", "16100000000", "20000000000", "20101000000", "20110000000", "20104000000", "20106000000", "20109000000", "20107000000", "20102000000", "20105000000", "20999000000", "20111000000", "20103000000", "20100000000", "20108000000", "20112000000", "12000000000", "12104000000", "12108000000", "12100000000", "12102000000", "12110000000", "12105000000", "12107000000", "12109000000", "12103000000", "12999000000", "12101000000", "12106000000", "14000000000", "14105000000", "14104000000", "14107000000", "14106000000", "14101000000", "14100000000", "14999000000", "14103000000", "14102000000", "24000000000", "24108000000", "24118000000", "24105000000", "24103000000", "24104000000", "24109000000", "24114000000", "24107000000", "24120000000", "24119000000", "24116000000", "24117000000", "24111000000", "24106000000", "24112000000", "24101000000", "24999000000", "24113000000", "24100000000", "24102000000", "24110000000", "24115000000", "30000000000", "30100000000", "30102000000", "30101000000", "10000000000", "10100000000", "10102000000", "10105000000", "10106000000", "10999000000", "10103000000", "10101000000", "10104000000", "13000000000", "13100000000", "13108000000", "13117000000", "13115000000", "13116000000", "13112000000", "13107000000", "13104000000", "13102000000", "13110000000", "13111000000", "13109000000", "13999000000", "13105000000", "13113000000", "13101000000", "13114000000", "13103000000", "27000000000", "27103000000", "27104000000", "27100000000", "27101000000", "27102000000", "27999000000", "25000000000", "25301000000", "25302000000", "25300000000", "25313000000", "25303000000", "25999000000", "25311000000", "25304000000", "25305000000", "25306000000", "25307000000", "25308000000", "25309000000", "25310000000", "25312000000", "29000000000", "29102000000", "29101000000", "29100000000", "29103000000", "29999000000", "21000000000", "21102000000", "21101000000", "21103000000", "21104000000", "21100000000", "21999000000", "21105000000", "18000000000", "18106000000", "18110000000", "18104000000", "18101000000", "18102000000", "18105000000", "18108000000", "18109000000", "18999000000", "18112000000", "18100000000", "18103000000", "18107000000", "18111000000", "26000000000", "26114000000", "26112000000", "26102000000", "26113000000", "26108000000", "26104000000", "26105000000", "26111000000", "26999000000", "26101000000", "26106000000", "26107000000", "26109000000", "26103000000", "26100000000", "23000000000", "23113000000", "23114000000", "23122000000", "23102000000", "23126000000", "23108000000", "23105000000", "23111000000", "23116000000", "23104000000", "23128000000", "23107000000", "23124000000", "23125000000", "23127000000", "23115000000", "23106000000", "23109000000", "23110000000", "23100000000", "23119000000", "23999000000", "23129000000", "23101000000", "23118000000", "23130000000", "23131000000", "23103000000", "23134000000", "23123000000", "23132000000", "23133000000", "23112000000", "23117000000", "19000000000", "19999000000", "19103000000", "19101000000", "19102000000", "19105000000", "19106000000", "19104000000", "19100000000", "28000000000", "28100000000", "28101000000", "15000000000", "15100000000", "15105000000", "15103000000", "15101000000", "15102000000", "15104000000", "15106000000", "15107000000", "15999000000", "17000000000", "17103000000", "17999000000", "17105000000", "17106000000", "11000000000", "11111000000", "11110000000", "11101000000", "11103000000", "11102000000", "11100000000", "11107000000", "11112000000", "11104000000", "11108000000", "11106000000", "11999000000", "11105000000", "11109000000" ], "type": "string", "description": "Filter Top Ads to a single industry. Pick a top-level category like 'Apparel & Accessories' to include every sub-industry below it, or pick a specific sub-industry to narrow further.", "default": "" }, "ccOrderBy": { "title": "Sort order", "enum": [ "for_you", "ctr", "like", "play_six_rate", "play_two_five_rate" ], "type": "string", "description": "How to order the Top Ads list.", "default": "for_you" }, "alibQuery": { "title": "Keywords or advertiser names", "type": "array", "description": "One or more search terms. Each runs as a separate search. Combined with Regions, you get one search per (keyword × region) pair. Outer quotes are stripped automatically (don't wrap terms in quotes unless you want TikTok's exact-match behavior, which usually returns 0 results).", "items": { "type": "string" } }, "alibQueryType": { "title": "Search by", "enum": [ "1", "2" ], "type": "string", "description": "What the search text matches against.", "default": "1" }, "alibAdvBizIds": { "title": "Advertiser business IDs", "type": "string", "description": "Optional comma-separated TikTok business IDs to refine results when the advertiser name above matches several brands. Use together with the advertiser name and set 'Search by' to 'Advertiser name'. The business ID alone is ignored by TikTok." }, "alibRegion": { "title": "Countries", "type": "array", "description": "Pick one or more EU/EEA + UK + Switzerland + Turkey countries. The actor runs a separate search per country. Leave empty to default to United Kingdom.", "items": { "type": "string", "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" ], "enumTitles": [ "Austria", "Belgium", "Bulgaria", "Switzerland", "Cyprus", "Czechia", "Germany", "Denmark", "Estonia", "Spain", "Finland", "France", "United Kingdom", "Greece", "Croatia", "Hungary", "Ireland", "Iceland", "Italy", "Liechtenstein", "Lithuania", "Luxembourg", "Latvia", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Sweden", "Slovenia", "Slovakia", "Turkey" ] } }, "alibPeriod": { "title": "Date range", "enum": [ "7", "30", "90", "180", "365", "custom" ], "type": "string", "description": "Time window for the ad's last-shown date. Choose 'Custom' to enter explicit start and end dates below.", "default": "30" }, "alibStartDate": { "title": "Start date (custom range)", "type": "string", "description": "Only used when Date range is set to Custom. ISO date like 2025-01-15." }, "alibEndDate": { "title": "End date (custom range)", "type": "string", "description": "Only used when Date range is set to Custom. ISO date like 2025-12-31." }, "alibSortType": { "title": "Sort order", "enum": [ "last_shown_date,desc", "first_shown_date,desc", "first_shown_date,asc", "last_shown_date,asc" ], "type": "string", "description": "How to order the Ads Library results.", "default": "last_shown_date,desc" }, "alibAdIds": { "title": "Ad IDs (optional)", "type": "array", "description": "Scrape specific Ads Library ads by ID. Each ID returns the full ad detail (advertiser name, dates, video URL, external link, call to action, advertising objective). One per line.", "items": { "type": "string" } }, "alibSkipAdIds": { "title": "Ad IDs to skip (optional)", "type": "array", "description": "Ad IDs already scraped in a previous run. The actor skips these before fetching, so you don't pay twice for the same ad. Useful for scheduled or incremental runs.", "items": { "type": "string" } }, "maxAds": { "title": "Max ads per search", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on ads returned per filter combination. Specific ad ID inputs always return one each, regardless of this cap.", "default": 100 }, "outputVideoDownload": { "title": "Download video ($)", "type": "boolean", "description": "Saves each ad's MP4 to your Apify key-value store. Adds savedVideoKey to the row. Billed at $0.003 per successful download.", "default": false }, "outputLandingPage": { "title": "Resolve landing page ($)", "type": "boolean", "description": "Follows the ad's click tracker URL to find the final merchant landing page. Ads Library only. Implies 'Fetch per-ad details' (the destination link is only on the detail endpoint). Billed at $0.001 per successful resolution.", "default": false }, "outputFetchDetails": { "title": "Enrich with ad details ($)", "type": "boolean", "description": "Adds extra fields to every row: call-to-action button text, advertising objective, destination URL, voiceover yes/no, comment and share counts, every country the ad ran in, campaign keywords, and more. Useful for deeper competitor analysis and creative reviews. Billed at $0.001 per ad enriched. Only successful enrichments are charged.", "default": false } } }, "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 } } } } } } } } } } ```