# TikTok Ads Scraper (`khadinakbar/tiktok-ads-scraper`) Actor Scrape TikTok Creative Center Top Ads. Get video URLs, brands, CTR tiers, Spark Ads, likes & creative intel. Filter 50+ countries, 19 industries, 7 objectives. No login. PPE: $0.003/ad. - **URL**: https://apify.com/khadinakbar/tiktok-ads-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, Lead generation, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 tiktok ad scrapeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 🎯 TikTok Ads Scraper β€” Creative Center Top Ads Spy **Extract competitor TikTok ad creatives, video URLs, brand names, CTR tiers, likes, CTAs & landing pages from TikTok Creative Center. Filter by 50+ countries, 19 industries, 7 objectives, and ad formats. No login or TikTok API key required.** Stop wasting hours scrolling through competitor ads manually. This actor intercepts TikTok's internal Top Ads API, returning structured JSON you can drop straight into a swipe file, creative brief, or spreadsheet β€” with direct video download links, advertiser metadata, and performance signals. --- ### What You Get | Field | Example | |---|---| | `ad_id` | 7613813410505555976 | | `brand_name` | "pacificmilllofts" (may be empty for Spark Ads) | | `ad_title` | "Love the space you're in with loft‑style apartments…" | | `video_url` | https://v16m-default.tiktokcdn.com/... (720p, signed β€” 24-48h expiry) | | `video_url_hd` | 1080p version when available | | `cover_url` | Static thumbnail (longer expiry) | | `video_id` | v10033g50000d7g424fog65u2g23hrg0 | | `video_duration_seconds` | 15.034 | | `video_width` / `video_height` | 720 / 1280 | | `likes` | 2,360 | | `ctr` | 0.61 (normalized 0-1) | | `ctr_tier` | top_10% / top_25% / top_50% / below_50% | | `cost_tier` | 0-5 (relative spend signal) | | `favorite` | true/false (TikTok-featured creative) | | `is_spark_ad` | true/false (boosted organic post?) | | `industry` | Beauty & Personal Care | | `industry_key` | label_17103000000 (raw sub-industry ID) | | `objective` | Conversion / Reach / Video View / Traffic | | `countries` | ["US", "CA", "GB"] | | `period_days` | 7 / 30 / 180 | | `ad_format` | "Spark Ads" / "All Formats" (filter echo) | | `tags` | When TikTok exposes them | | `scraped_at` | ISO 8601 | | `source_url` | Full Creative Center URL with filters | Use `responseFormat: "concise"` for a **14-field agent-friendly** output (~250 tokens/ad) β€” drops video_id, dimensions, raw CTR number, cost_tier, favorite flag, industry_key, ad_format, tags, source_url. --- ### πŸ’° Pricing **Pay per event** β€” you only pay for ads actually scraped. | Event | Price | |---|---| | Actor start | $0.00005 per GB RAM | | TikTok ad scraped | **$0.003** per ad | **Typical cost:** A 50-ad run is ~$0.15. A 500-ad swipe-file build is ~$1.50. Compare that to: - Buying a competitor ad-spy SaaS at $99–199/month - Hiring a VA to manually screenshot creatives ($10+/hour) --- ### 🎯 Who This Is For - **Performance marketers** building swipe files before launching DTC campaigns - **Creative agencies** doing client research and pitch decks - **E-commerce brands** spotting winning ad angles before competitors do - **Affiliate marketers & dropshippers** finding viral product creatives - **Market researchers** tracking ad trends across markets - **AI agents** (Claude/GPT/Cursor) that need structured TikTok ad data --- ### ⚑ Quickstart #### 1. Apify Console (UI) 1. Set **Country** (e.g. `πŸ‡ΊπŸ‡Έ United States`) 2. Set **Industry** (e.g. `Beauty & Personal Care`) 3. Set **Period** (e.g. `Last 7 Days`) 4. Set **Max Results** (e.g. `50`) 5. Click **Start** #### 2. Via API ```bash curl -X POST "https://api.apify.com/v2/acts/khadinakbar~tiktok-ads-scraper/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "country": "US", "industry": "Beauty & Personal Care", "period": "7", "orderBy": "CTR", "maxResults": 50 }' ```` #### 3. Node.js / TypeScript ```typescript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('khadinakbar/tiktok-ads-scraper').call({ country: 'US', industry: 'E-commerce & Shopping', period: '30', objective: 'Conversions', orderBy: 'CTR', maxResults: 100, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(`Scraped ${items.length} top TikTok ads`); ``` #### 4. Python ```python from apify_client import ApifyClient client = ApifyClient("YOUR_API_TOKEN") run = client.actor("khadinakbar/tiktok-ads-scraper").call(run_input={ "country": "GB", "industry": "Fashion & Apparel", "period": "30", "adFormat": "Spark Ads", "maxResults": 100, }) for ad in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"{ad['brand_name']}: {ad['ad_title']}") ``` #### 5. Claude Desktop / MCP Add to your Claude Desktop or any MCP client: ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com?tools=khadinakbar/tiktok-ads-scraper", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` Then ask Claude: *"Find me the top 20 beauty ads on TikTok in the US this week with spark ads only."* *** ### 🎨 Use Cases #### Creative Swipe Files Pull the top 50 ads in your vertical every week. Save video URLs + landing pages to a Notion database. Study CTA patterns, hook structures, and CTR-tier performers. #### Competitor Intelligence Filter by `brand_name` in your dataset post-processing to track a specific competitor's TikTok ad output over time. #### Winning Product Research E-commerce? Filter by `Conversions` objective + `E-commerce & Shopping` industry + `top_10%` CTR tier. These are the proven-selling creatives. #### Spark Ads Partner Research Set `adFormat: "Spark Ads"` to find creators brands are partnering with β€” great for influencer outreach shortlists. #### Agency Pitch Decks Show prospects the actual top-performing ads in their vertical with real CTR data. Instant credibility. #### Ad Trend Reports Run monthly across 5 countries in your category. Track format shifts (Spark β†’ Non-Spark), CTA evolution, and emerging themes. *** ### πŸ”Œ Complements Your Ad Intelligence Stack Khadin's ad trilogy β€” **cross-reference across platforms**: - **[meta-ad-library-scraper](https://apify.com/khadinakbar/meta-ad-library-scraper)** β€” Facebook & Instagram ads from Meta Ad Library - **[google-ads-transparency-scraper](https://apify.com/khadinakbar/google-ads-transparency-scraper)** β€” Google Ads creatives (search, display, YouTube, shopping) - **tiktok-ads-scraper** ← you are here Run all three for the same brand or keyword to get a full picture of their paid media strategy. Also useful: - **[tiktok-trending-hashtags-scraper](https://apify.com/khadinakbar/tiktok-trending-hashtags-scraper)** β€” trending TikTok hashtags for organic research - **[tiktok-profile-scraper](https://apify.com/khadinakbar/tiktok-profile-scraper)** β€” TikTok creator profiles - **[shopify-all-in-one-scraper](https://apify.com/khadinakbar/shopify-all-in-one-scraper)** β€” find the Shopify stores behind the ads *** ### βš™οΈ Filter Reference #### Country (50+) US, GB, CA, AU, DE, FR, JP, KR, BR, IN, MX, IT, ES, NL, SE, NO, DK, FI, PL, RU, TR, SA, AE, EG, ZA, NG, ID, TH, VN, MY, PH, SG, TW, HK, AR, CL, CO, PE, IL, AT, BE, CH, CZ, HU, RO, UA, KZ, PK, BD, NZ. Leave blank for global. #### Industry (19) All Industries Β· Gaming Β· E-commerce & Shopping Β· Beauty & Personal Care Β· Food & Beverage Β· Health & Fitness Β· Entertainment Β· Sports & Outdoors Β· Finance Β· Education Β· Travel Β· Business Services Β· Fashion & Apparel Β· Technology Β· Home & DΓ©cor Β· Parenting & Kids Β· Media & Entertainment Β· News & Information Β· Music #### Campaign Objective (7) All Objectives Β· Traffic Β· App Install Β· Conversions Β· Reach Β· Video Views Β· Lead Generation Β· Engagement #### Ad Format (3) All Formats Β· Spark Ads (boosted organic posts) Β· Non-Spark Ads (paid creative) Β· Collection Ads (multi-product shopping) #### Sort Order (5) For You Β· Likes Β· CTR Β· Impressions Β· Cost #### Period (3) Last 7 Days Β· Last 30 Days Β· Last 180 Days *** ### πŸ›‘οΈ Reliability - **Residential proxies by default** β€” bypasses TikTok's datacenter blocks - **Session consistency** β€” one proxy + one cookie jar across related requests - **API response interception** β€” high-fidelity data capture from TikTok's internal `creative_radar_api/v1/top_ads` endpoint - **Graceful degradation** β€” partial results pushed with `_summary` record if blocks occur - **Auto-scroll pagination** β€” keeps loading more ads until maxResults or no more available - **Retry discipline** β€” 403/429 triggers session rotation; 5xx triggers exponential backoff - **Circuit breaker** β€” aborts cleanly when target is clearly down rather than burning your proxy budget *** ### ❓ FAQ **Do I need a TikTok account or API key?** No. TikTok Creative Center Top Ads is public. Just run the actor. **Why do some `video_url` links stop working after a day?** TikTok CDN URLs are signed and expire in 24–48h. Download immediately after the run, or re-run to get fresh URLs. The `cover_url` (thumbnail) lasts longer. **What's the difference between Top Ads (this actor) and the EU Ad Library?** TikTok Creative Center **Top Ads** (this actor): global, curated highest-performing ads across 50+ countries. Public, no login. Focused on creative intel β€” video URLs, CTR tiers, likes. TikTok EU **Ad Library**: DSA-compliance archive of every ad run in EU/EEA/UK with targeting & reach data. Wider coverage but EU-only and slower. **Why are landing URLs, CTA text, advertiser IDs, and exact run dates not in the output?** TikTok Creative Center's list endpoint doesn't expose those fields β€” they live behind a per-ad detail call. This V1 returns only what the list API provides (fast, cheap, reliable). A detail-enrichment mode is on the roadmap β€” upvote it in the Issues tab. **Why is `brand_name` empty on some ads?** Many Spark Ads (boosted organic posts from creators) don't have a registered brand name in TikTok's list API β€” the ad surfaces under the creator's username or appears unbranded. Paid creative from registered advertisers has brand\_name populated. **How many ads per filter combination can I get?** Without login, TikTok Creative Center typically surfaces 20–100 ads per filter combo. This actor auto-scrolls to load all available. For bigger datasets, vary filters (country Γ— industry) across multiple runs. **What do CTR / impression / cost tiers mean?** TikTok doesn't expose raw numbers β€” they normalize to 0–1 scores. The actor buckets CTR into `top_10%`, `top_25%`, `top_50%`, `below_50%` so you can filter on performance. **Is this legal?** Yes. TikTok Creative Center is a public marketing tool TikTok themselves operates at [ads.tiktok.com/business/creativecenter](https://ads.tiktok.com/business/creativecenter). This actor scrapes only publicly-available ad data. Use responsibly and comply with your jurisdiction's data and competitive-intelligence rules. **What's the typical cost per run?** 50 ads = $0.15. 200 ads = $0.60. 500 ads = $1.50. A dedicated ad-spy SaaS charges $99–$199/month for similar data. **Can I run this on a schedule?** Yes β€” use Apify's Scheduler tab to run daily or weekly for the same filters. Combine with a webhook to push new ads to Slack/Notion. *** ### πŸ”§ Tips & Tricks - **Narrow filters first.** A country + industry combo returns cleaner, more actionable results than global + all industries. - **Sort by CTR** when researching creative hooks β€” these are proven click-drivers. - **Sort by Cost** to find the brands spending most (likely scaling their winners). - **Spark Ads only** is the shortcut to finding creator partnership inspiration. - **Run across multiple periods (7 + 30 + 180)** for the same filters to separate short-term trends from long-running winners. - **Cross-reference with Meta Ad Library scraper** β€” brands running similar creative on both platforms have battle-tested that angle. *** ### πŸ“ Changelog - **1.0.0** (2026-04-24) β€” Initial release. Top Ads scraping via Creative Center API interception. Residential proxies, auto-scroll pagination, concise/detailed output modes. *** ### βš–οΈ Legal Disclaimer This actor scrapes publicly-available data from TikTok's public Creative Center at `ads.tiktok.com/business/creativecenter`. It does not bypass authentication, access protected content, or collect personal user data. Ad creatives remain the property of their respective advertisers. Use of scraped data is subject to TikTok's Terms of Service and applicable copyright, competitive-intelligence, and data-protection laws in your jurisdiction. The scraper is provided "as-is"; TikTok may change their Creative Center or its underlying API at any time, which may temporarily affect results. This actor is not affiliated with, endorsed by, or sponsored by TikTok / ByteDance. *** **Built by [Khadin Akbar](https://apify.com/khadinakbar)** β€” 50+ production Apify actors. [See the full actor portfolio β†’](https://apify.com/khadinakbar) # Actor input Schema ## `period` (type: `string`): Time window for the Top Ads ranking. Use '7' for past 7 days (hottest creatives right now), '30' for monthly top performers, '180' for long-running winners. Defaults to 7. This is NOT the date range of when ads ran β€” it's TikTok's ranking window. ## `country` (type: `string`): Two-letter ISO country code filter (e.g. 'US', 'GB', 'JP'). Leave empty for global top ads across all regions. Not a city or region. Country determines which local advertisers surface in results. ## `industry` (type: `string`): Filter top ads by industry vertical. Use this when researching a specific niche like 'Beauty & Personal Care', 'Gaming', 'E-commerce & Shopping'. Select 'All Industries' for cross-niche top performers. Not a product category β€” this is TikTok's advertiser vertical classification. ## `objective` (type: `string`): Filter ads by the advertiser's stated campaign objective. 'Conversions' surfaces DTC and e-commerce sales ads. 'App Install' for mobile app ads. 'Traffic' for click-focused ads. Select 'All Objectives' for broader coverage. Only one objective can be selected per run. ## `adFormat` (type: `string`): Filter by TikTok ad format. 'Spark Ads' are boosted organic posts (creator partnerships). 'Non-Spark Ads' are traditional paid creative. 'Collection Ads' are multi-product shopping ads. Select 'All Formats' for every type. Not the same as ad placement. ## `orderBy` (type: `string`): How to rank the returned ads. 'For You' is TikTok's recommended mix. 'Likes' sorts by engagement. 'CTR' surfaces highest click-through performers (best for creative research). 'Impressions' sorts by estimated reach. 'Cost' by estimated ad spend. Default 'For You'. ## `keyword` (type: `string`): Optional free-text keyword to search across ad creative text, brand names, and CTAs (e.g. 'skincare routine', 'black friday'). Leave empty for no keyword filter. This is a Creative Center search term, NOT a hashtag or campaign ID. ## `maxResults` (type: `integer`): Maximum number of ads to extract (1–500). TikTok Creative Center typically surfaces 20–100 ads per filter combination without login; scraper auto-scrolls to load more. Use 20–50 for quick creative research, 200+ for bulk swipe-file building. Each ad is billed at $0.003. ## `responseFormat` (type: `string`): Output detail level. 'concise' returns only the essential fields (14 keys, ~250 tokens/ad) β€” ideal for AI agents and quick swipe files. 'detailed' returns all 20+ fields including advertiser ID, HD video URL, CTR/CVR numbers, days running, and tags (~450 tokens/ad). Default is 'detailed'. ## `proxyConfiguration` (type: `object`): Proxy settings for reliability. Apify default proxy works well for TikTok Creative Center. Switch to Residential only if you see rate limits or empty results on repeated runs. ## Actor input object example ```json { "period": "7", "country": "US", "industry": "All Industries", "objective": "All Objectives", "adFormat": "All Formats", "orderBy": "For You", "keyword": "", "maxResults": 50, "responseFormat": "detailed", "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `topAds` (type: `string`): Dataset of TikTok Creative Center Top Ads. Each item contains ad creative metadata, video/cover URLs, performance tiers, CTR scoring, engagement stats, brand info, and filter context. Concise format drops advertiser\_id, advertiser\_logo, video\_url\_hd, CTR/CVR/impression/cost numbers, first/last shown dates, days\_running, tags, keywords. # 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 = { "period": "7", "country": "US", "industry": "All Industries", "objective": "All Objectives", "adFormat": "All Formats", "orderBy": "For You", "keyword": "", "maxResults": 50, "responseFormat": "detailed", "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/tiktok-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 = { "period": "7", "country": "US", "industry": "All Industries", "objective": "All Objectives", "adFormat": "All Formats", "orderBy": "For You", "keyword": "", "maxResults": 50, "responseFormat": "detailed", "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/tiktok-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 '{ "period": "7", "country": "US", "industry": "All Industries", "objective": "All Objectives", "adFormat": "All Formats", "orderBy": "For You", "keyword": "", "maxResults": 50, "responseFormat": "detailed", "proxyConfiguration": { "useApifyProxy": true } }' | apify call khadinakbar/tiktok-ads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/tiktok-ads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Scraper", "description": "Scrape TikTok Creative Center Top Ads. Get video URLs, brands, CTR tiers, Spark Ads, likes & creative intel. Filter 50+ countries, 19 industries, 7 objectives. No login. PPE: $0.003/ad.", "version": "1.0", "x-build-id": "tpRfPKWn5bigw93At" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-tiktok-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/khadinakbar~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-tiktok-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/khadinakbar~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-tiktok-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", "properties": { "period": { "title": "Time Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window for the Top Ads ranking. Use '7' for past 7 days (hottest creatives right now), '30' for monthly top performers, '180' for long-running winners. Defaults to 7. This is NOT the date range of when ads ran β€” it's TikTok's ranking window.", "default": "7" }, "country": { "title": "Country", "enum": [ "", "US", "GB", "CA", "AU", "DE", "FR", "JP", "KR", "BR", "IN", "MX", "IT", "ES", "NL", "SE", "NO", "DK", "FI", "PL", "RU", "TR", "SA", "AE", "EG", "ZA", "NG", "ID", "TH", "VN", "MY", "PH", "SG", "TW", "HK", "AR", "CL", "CO", "PE", "IL", "AT", "BE", "CH", "CZ", "HU", "RO", "UA", "KZ", "PK", "BD", "NZ" ], "type": "string", "description": "Two-letter ISO country code filter (e.g. 'US', 'GB', 'JP'). Leave empty for global top ads across all regions. Not a city or region. Country determines which local advertisers surface in results.", "default": "US" }, "industry": { "title": "Industry / Vertical", "enum": [ "All Industries", "Gaming", "E-commerce & Shopping", "Beauty & Personal Care", "Food & Beverage", "Health & Fitness", "Entertainment", "Sports & Outdoors", "Finance", "Education", "Travel", "Business Services", "Fashion & Apparel", "Technology", "Home & DΓ©cor", "Parenting & Kids", "Media & Entertainment", "News & Information", "Music" ], "type": "string", "description": "Filter top ads by industry vertical. Use this when researching a specific niche like 'Beauty & Personal Care', 'Gaming', 'E-commerce & Shopping'. Select 'All Industries' for cross-niche top performers. Not a product category β€” this is TikTok's advertiser vertical classification.", "default": "All Industries" }, "objective": { "title": "Campaign Objective", "enum": [ "All Objectives", "Traffic", "App Install", "Conversions", "Reach", "Video Views", "Lead Generation", "Engagement" ], "type": "string", "description": "Filter ads by the advertiser's stated campaign objective. 'Conversions' surfaces DTC and e-commerce sales ads. 'App Install' for mobile app ads. 'Traffic' for click-focused ads. Select 'All Objectives' for broader coverage. Only one objective can be selected per run.", "default": "All Objectives" }, "adFormat": { "title": "Ad Format", "enum": [ "All Formats", "Spark Ads", "Non-Spark Ads", "Collection Ads" ], "type": "string", "description": "Filter by TikTok ad format. 'Spark Ads' are boosted organic posts (creator partnerships). 'Non-Spark Ads' are traditional paid creative. 'Collection Ads' are multi-product shopping ads. Select 'All Formats' for every type. Not the same as ad placement.", "default": "All Formats" }, "orderBy": { "title": "Sort Order", "enum": [ "For You", "Likes", "CTR", "Impressions", "Cost" ], "type": "string", "description": "How to rank the returned ads. 'For You' is TikTok's recommended mix. 'Likes' sorts by engagement. 'CTR' surfaces highest click-through performers (best for creative research). 'Impressions' sorts by estimated reach. 'Cost' by estimated ad spend. Default 'For You'.", "default": "For You" }, "keyword": { "title": "Keyword Search", "type": "string", "description": "Optional free-text keyword to search across ad creative text, brand names, and CTAs (e.g. 'skincare routine', 'black friday'). Leave empty for no keyword filter. This is a Creative Center search term, NOT a hashtag or campaign ID.", "default": "" }, "maxResults": { "title": "Max Ads to Return", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of ads to extract (1–500). TikTok Creative Center typically surfaces 20–100 ads per filter combination without login; scraper auto-scrolls to load more. Use 20–50 for quick creative research, 200+ for bulk swipe-file building. Each ad is billed at $0.003.", "default": 50 }, "responseFormat": { "title": "Response Format", "enum": [ "detailed", "concise" ], "type": "string", "description": "Output detail level. 'concise' returns only the essential fields (14 keys, ~250 tokens/ad) β€” ideal for AI agents and quick swipe files. 'detailed' returns all 20+ fields including advertiser ID, HD video URL, CTR/CVR numbers, days running, and tags (~450 tokens/ad). Default is 'detailed'.", "default": "detailed" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for reliability. Apify default proxy works well for TikTok Creative Center. Switch to Residential only if you see rate limits or empty results on repeated runs.", "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 } } } } } } } } } } ```