# TikTok Ads Scraper (`data_xplorer/tiktok-ads-scraper`) Actor ๐Ÿฅ‡ The most complete TikTok Ads scraper. Two modes: Ads Library (EU transparency, targeting, spend) + Top Ads (Creative Center, engagement metrics, 80+ countries). Search by keyword, advertiser, industry. Extract videos, performance data & creative assets. - **URL**: https://apify.com/data\_xplorer/tiktok-ads-scraper.md - **Developed by:** [Data Xplorer](https://apify.com/data_xplorer) (community) - **Categories:** AI, Lead generation, Social media - **Stats:** 161 total users, 61 monthly users, 99.8% runs succeeded, 2 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.50 / 1,000 results 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: Library + Top Ads The most complete TikTok advertising intelligence tool on Apify. Two powerful modes in one Actor: - **๐Ÿ“š Ads Library**: EU transparency data from [library.tiktok.com](https://library.tiktok.com) - **๐ŸŽฏ Top Ads**: Performance-ranked ads from [TikTok Creative Center](https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en) ![TikTok Ads Scraper](https://i.ibb.co/m105zws/fil-u-E21-Yt-Zv-Fy2-Nq-XBE-1.jpg) --- ### ๐ŸŽฏ Two Modes, One Actor #### ๐Ÿ“š Ads Library Mode (EU Transparency) Access TikTok's official Ad Library for the European market. Get full transparency data: advertiser info, targeting, audience size, spend estimates, impressions, media assets, and more. **Best for:** Compliance research, competitor monitoring in EU/EEA, advertiser-level analysis, spend & audience insights. #### ๐ŸŽฏ Top Ads Mode (Creative Center) Access TikTok's Creative Center Top Ads, a curated ranking of the best-performing ads worldwide. Get engagement metrics (likes, CTR, budget level), video assets, and industry classification. **Best for:** Creative inspiration, ad benchmarking, industry trend analysis, competitive intelligence. --- ### ๐Ÿ’Ž Key Features | Feature | Ads Library | Top Ads | |---------|:-----------:|:-------:| | ๐ŸŒ Global coverage | EU/EEA countries | 80+ countries | | ๐Ÿ” Keyword search | โœ… | โœ… | | ๐Ÿข Advertiser search | โœ… | - | | ๐Ÿ”— Direct URL import | โœ… | - | | โค๏ธ Engagement metrics (likes, CTR, budget) | - | โœ… | | ๐Ÿ“ˆ Impressions & audience estimates | โœ… (with details) | - | | ๐Ÿ’ฐ Spend estimates | โœ… (with details) | - | | ๐ŸŽฏ Targeting data (age, gender, region) | โœ… (with details) | - | | ๐Ÿท๏ธ Industry & objective classification | - | โœ… | | ๐ŸŽฌ Video URLs | Up to 1080p | 720p | | ๐Ÿ‘ค Sponsor & advertiser info | โœ… (with details) | Brand name | | โšก Speed | ~2-5 ads/sec | ~20 ads/sec | > ๐Ÿ’ก **Tip:** In Library mode, enable **"Fetch Ad Details"** to get impressions, spend, targeting, sponsor and audience size. Without it, scraping is ~3x faster but only returns basic ad info. --- ### ๐Ÿ“š Ads Library Mode #### Search Options 1. **๐Ÿ”ค Keyword Search**: Search ads by content keywords 2. **๐Ÿข Advertiser Name**: Find all ads from a specific advertiser (optionally with Advertiser ID for precision) 3. **๐ŸŒ Direct URL**: Paste any TikTok Ads Library URL and all parameters are auto-extracted #### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | mode | string | `"library"` | Set to `"library"` | | region | string | `"all"` | Country code (FR, DE, GB, etc.) or "all" | | startDate | string | `"2025-01-01"` | Start date (YYYY-MM-DD) | | endDate | string | `""` | End date (empty = today) | | queryType | string | `"2"` | 1 = Keyword, 2 = Advertiser Name, url = Direct URL | | query | string | `""` | Search term, advertiser name, or full URL | | advertiserBizId | string | `""` | Optional advertiser business ID | | maxAds | number | `20` | Maximum ads to collect | | fetchDetails | boolean | `true` | Fetch targeting, sponsor, audience, spend, impressions | | proxyConfiguration | object | Apify Proxy | Proxy settings | #### Input Example: Advertiser Name + ID ```json { "mode": "library", "region": "FR", "startDate": "2026-01-01", "endDate": "2026-06-01", "queryType": "2", "query": "LEVI STRAUSS & CO.", "advertiserBizId": "6886458055832109825", "maxAds": 10, "fetchDetails": true } ```` #### Input Example: Keyword Search ```json { "mode": "library", "region": "GB", "startDate": "2025-01-01", "queryType": "1", "query": "football", "maxAds": 20, "fetchDetails": true } ``` #### Input Example: Direct TikTok URL ```json { "mode": "library", "queryType": "url", "query": "https://library.tiktok.com/ads?region=FR&start_time=1777123937000&end_time=1779715937000&adv_name=LEVI%20STRAUSS%20%26%20CO.&adv_biz_ids=6886458055832109825&query_type=2&sort_type=last_shown_date,desc", "maxAds": 10, "fetchDetails": true } ``` #### Output Example (Library) ```json { "AD ID": "1820020351685681", "Advertiser Name": "Bouazza Helmi", "AD Preview": "https://p21-ad-sg.ibyteimg.com/origin/...", "Ad Dates": [ { "FirstShown": "2025-01-01", "FirstShownTimestamp": 1735689600 }, { "LastShown": "2025-03-08", "LastShownTimestamp": 1741392000 } ], "Ad Audience": "100K-200K", "Ad Details": [ { "Estimated Audience": "100K-200K" }, { "Spent": "" }, { "Impression": "" }, { "Sponsor": "Digital Marketing Agency" }, { "Target Audience Size": "5.2M-6.4M" } ], "Ad Media": [ "Video 1: https://library.tiktok.com/api/v1/cdn/...", "Cover 1: https://p21-ad-sg.ibyteimg.com/origin/..." ], "Ad Targeting": { "regions": [{ "region": "FR", "impressions": "152K" }], "age": [{ "region": "FR", "18-24": true, "25-34": true, "35-44": true }], "gender": [{ "region": "FR", "female": true, "male": true }] }, "Ad Sponsor": "Digital Marketing Agency", "Ad Target Audience Size": "5.2M-6.4M", "Ad Detail URL": "https://library.tiktok.com/ads/detail/?ad_id=1820020351685681" } ``` #### Library Metrics (with fetchDetails enabled) | Field | Description | |-------|-------------| | `Ad Audience` | Estimated audience reach (e.g. "100K-200K") | | `Impression` | Number of impressions served | | `Spent` | Estimated ad spend | | `Ad Sponsor` | Name of the sponsoring entity | | `Ad Target Audience Size` | Total estimated target audience (e.g. "5.2M-6.4M") | | `Ad Targeting` | Breakdown by region (with impressions), age groups, and gender | | `Ad Media` | Direct URLs to videos, cover images, and creatives | *** ### ๐ŸŽฏ Top Ads Mode #### Filters - **๐Ÿ” Keyword**: Search by brand, product, or topic - **๐ŸŒ Countries**: Multi-select from 80+ countries - **๐Ÿท๏ธ Industries**: 21 parent categories + 200+ sub-industries - **๐ŸŽฏ Objectives**: Traffic, Conversions, App Installs, Video Views, Reach, Lead Gen, Product Sales - **๐Ÿ—ฃ๏ธ Language**: Filter by ad language (17 languages) - **โค๏ธ Likes percentile**: Top 1-20%, 21-40%, etc. - **๐Ÿ“… Time period**: Last 7 days, 30 days, or 6 months - **๐Ÿ“Š Sort by**: Likes, Reach, CTR, CVR, 2s/6s view rates #### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | mode | string | - | Set to `"top_ads"` | | topAdsKeyword | string | `""` | Search keyword (leave empty to browse all) | | topAdsCountryCode | array | `[]` | Country codes, e.g. `["FR", "DE"]` | | topAdsPeriod | string | `"7"` | `"7"`, `"30"`, or `"180"` days | | topAdsOrderBy | string | `"like"` | Sort: like, impression, ctr, cvr, play\_2s\_rate, play\_6s\_rate | | topAdsIndustry | array | `[]` | Industry IDs (parent or sub-industry) | | topAdsObjective | array | `[]` | Objective IDs: 1=Traffic, 2=App, 3=Conversions, etc. | | topAdsLanguage | string | `""` | Language code (fr, en, de, etc.) | | topAdsLikeRange | string | `""` | Likes percentile: 1-5 | | topAdsMaxItems | number | `100` | Maximum ads to collect (up to 500) | #### Input Example: Top Ads in France (Education) ```json { "mode": "top_ads", "topAdsCountryCode": ["FR"], "topAdsPeriod": "30", "topAdsOrderBy": "like", "topAdsIndustry": ["10000000000"], "topAdsLanguage": "fr", "topAdsMaxItems": 50 } ``` #### Input Example: Keyword Search ```json { "mode": "top_ads", "topAdsKeyword": "netflix", "topAdsCountryCode": ["FR", "US"], "topAdsPeriod": "30", "topAdsOrderBy": "like", "topAdsMaxItems": 20 } ``` #### Input Example: Sub-industry Filter ```json { "mode": "top_ads", "topAdsCountryCode": ["FR"], "topAdsPeriod": "30", "topAdsIndustry": ["14103000000", "14104000000"], "topAdsObjective": ["3"], "topAdsMaxItems": 40 } ``` #### Output Example (Top Ads) ```json { "id": "7636363707227226130", "ad_title": "Des fiches prรชtes ร  apprendre pour booster tes rรฉvisions CRPE", "brand_name": "Not Mention", "like": 585, "cost": 1, "cost_readable": "Medium", "ctr": 0.14, "ctr_readable": "Top 14%", "industry_key": "label_10101000000", "industry": "Primary & Secondary Education & K-12", "objective_key": "campaign_objective_conversion", "objective": "Conversions", "video_duration": 10.467, "video_cover": "https://p16-common-sign.tiktokcdn.com/...", "video_url_720p": "https://v16m-default.tiktokcdn.com/...", "video_width": 720, "video_height": 1280, "creative_center_url": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en?ad_id=7636363707227226130" } ``` #### Top Ads Metrics | Field | Description | |-------|-------------| | `like` | Number of likes on the ad | | `cost_readable` | Budget level: **Low**, **Medium**, or **High** | | `ctr_readable` | CTR percentile ranking (e.g. "Top 14%" = outperforms 86% of ads) | | `industry` | Human-readable industry label (200+ categories) | | `objective` | Campaign objective: Traffic, Conversions, App Installs, etc. | | `video_url_720p` | Direct download URL for the ad video (720p) | *** ### ๐Ÿ’ก Use Cases & Ideas #### ๐Ÿข For Marketing & Ad Agencies - **Creative swipe files**: Build a library of top-performing TikTok ads in your client's industry. Filter by country, objective, and sub-industry to find exactly the right inspiration. - **Pitch preparation**: Show clients what competitors are running and what's working best. Use budget and CTR data to benchmark performance. - **Ad spend monitoring**: Track how much competitors invest across regions with Library mode's spend estimates. #### ๐Ÿ›๏ธ For E-Commerce & DTC Brands - **Competitor tracking**: Monitor what ads your competitors are running in real-time across EU markets. Get notified when new campaigns launch. - **Creative inspiration**: Find the highest-engagement ads in your product category (Skincare, Cosmetics, Fashion...) and study what makes them work. - **Market entry research**: Before launching in a new country, analyze what ad formats, messages, and budgets work best in that market. #### ๐Ÿ“Š For Data Analysts & Researchers - **Industry benchmarking**: Collect hundreds of ads across industries to build performance benchmarks (CTR percentiles, budget tiers, engagement rates). - **Trend detection**: Run weekly scrapes to track which industries, objectives, and ad formats are gaining traction over time. - **Academic research**: Study advertising patterns, targeting strategies, and political ad transparency across the EU. #### ๐ŸŽฏ For Media Buyers & Performance Marketers - **Winning ad formats**: Sort by CTR or conversion rate to find the highest-performing creative formats in your niche. - **Budget intelligence**: Understand whether top performers are Low, Medium, or High budget, and find opportunities where low-budget ads outperform. - **Targeting insights**: Use Library mode's age, gender, and regional targeting data to refine your own audience strategy. #### ๐Ÿ”— Integration Ideas - **Feed into Google Sheets or Airtable**: Use Apify integrations to automatically push new ads into your creative tracking spreadsheet. - **Build a Slack alert**: Get notified when a competitor launches a new ad or when a top-performing ad appears in your industry. - **Power a dashboard**: Connect the output to Looker Studio, Tableau, or any BI tool for real-time ad intelligence dashboards. - **Train AI models**: Use the video URLs and ad copy to train creative analysis models or generate ad variations. *** ### ๐Ÿค Support & Resources Found a bug or want to request a feature? Open an issue. **โค๏ธ Enjoying the scraper?** Leave a review [here](https://console.apify.com/actors/rFFzT2mRuOd1K4iTM/reviews) # Actor input Schema ## `mode` (type: `string`): Choose which TikTok data source to scrape. ## `region` (type: `string`): Region code for which you want to scrape ads ## `startDate` (type: `string`): Start date for ads (format: YYYY-MM-DD) ## `endDate` (type: `string`): End date for ads (format: YYYY-MM-DD). Leave empty for current date. ## `queryType` (type: `string`): Type of search query ## `query` (type: `string`): For Keyword: enter a search term. For Advertiser Name: enter the exact advertiser name. For URL: paste a full TikTok Ads Library URL. Leave empty to search all ads. ## `advertiserBizId` (type: `string`): Optional advertiser business ID (numeric). Only used when Query Type is 'Advertiser Name'. ## `maxAds` (type: `integer`): Maximum number of ads to scrape ## `fetchDetails` (type: `boolean`): Enable to fetch detailed information for each ad (targeting, sponsor, etc.). ## `topAdsKeyword` (type: `string`): Search top ads by keyword (brand name, product, topicโ€ฆ). Leave empty to browse all top ads. ## `topAdsCountryCode` (type: `array`): Select one or more countries to filter top ads (leave empty for global results). ## `topAdsPeriod` (type: `string`): Number of days to look back. ## `topAdsOrderBy` (type: `string`): Sort top ads by metric. ## `topAdsIndustry` (type: `array`): Select one or more industries or sub-industries to filter top ads (leave empty for all). ## `topAdsObjective` (type: `array`): Select one or more campaign objectives to filter top ads (leave empty for all objectives). ## `topAdsLanguage` (type: `string`): Filter ads by language. Leave empty for all languages. ## `topAdsLikeRange` (type: `string`): Filter by likes performance percentile. Leave empty for all. ## `topAdsMaxItems` (type: `integer`): Maximum number of top ads to return. ## `proxyConfiguration` (type: `object`): Proxy for Ads Library mode. Top Ads mode runs without proxy for best performance. ## Actor input object example ```json { "mode": "library", "region": "all", "startDate": "2025-01-01", "endDate": "", "queryType": "1", "query": "Netflix", "advertiserBizId": "", "maxAds": 100, "fetchDetails": false, "topAdsKeyword": "", "topAdsPeriod": "7", "topAdsOrderBy": "like", "topAdsLanguage": "", "topAdsLikeRange": "", "topAdsMaxItems": 100, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `topAdsOverview` (type: `string`): No description ## `topAdsAnalytics` (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 = { "startDate": "2025-01-01", "queryType": "1", "query": "Netflix", "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("data_xplorer/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 = { "startDate": "2025-01-01", "queryType": "1", "query": "Netflix", "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("data_xplorer/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 '{ "startDate": "2025-01-01", "queryType": "1", "query": "Netflix", "proxyConfiguration": { "useApifyProxy": true } }' | apify call data_xplorer/tiktok-ads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=data_xplorer/tiktok-ads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Ads Scraper", "description": "๐Ÿฅ‡ The most complete TikTok Ads scraper. Two modes: Ads Library (EU transparency, targeting, spend) + Top Ads (Creative Center, engagement metrics, 80+ countries). Search by keyword, advertiser, industry. Extract videos, performance data & creative assets.", "version": "3.1", "x-build-id": "ypPhO4XlVzjTuwS8h" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/data_xplorer~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-data_xplorer-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/data_xplorer~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-data_xplorer-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/data_xplorer~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-data_xplorer-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": { "mode": { "title": "Scraping Mode", "enum": [ "library", "top_ads" ], "type": "string", "description": "Choose which TikTok data source to scrape.", "default": "library" }, "region": { "title": "Region", "enum": [ "all", "FR", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "DE", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "CH", "TR", "GB" ], "type": "string", "description": "Region code for which you want to scrape ads", "default": "all" }, "startDate": { "title": "Start Date", "type": "string", "description": "Start date for ads (format: YYYY-MM-DD)", "default": "2025-01-01" }, "endDate": { "title": "End Date", "type": "string", "description": "End date for ads (format: YYYY-MM-DD). Leave empty for current date.", "default": "" }, "queryType": { "title": "Query Type", "enum": [ "1", "2", "url" ], "type": "string", "description": "Type of search query", "default": "2" }, "query": { "title": "Search Keyword, Advertiser Name or URL", "type": "string", "description": "For Keyword: enter a search term. For Advertiser Name: enter the exact advertiser name. For URL: paste a full TikTok Ads Library URL. Leave empty to search all ads.", "default": "" }, "advertiserBizId": { "title": "Advertiser ID (optional, Advertiser mode only)", "type": "string", "description": "Optional advertiser business ID (numeric). Only used when Query Type is 'Advertiser Name'.", "default": "" }, "maxAds": { "title": "Maximum Number of Ads", "minimum": 1, "type": "integer", "description": "Maximum number of ads to scrape", "default": 100 }, "fetchDetails": { "title": "Fetch Ad Details (Optional)", "type": "boolean", "description": "Enable to fetch detailed information for each ad (targeting, sponsor, etc.).", "default": false }, "topAdsKeyword": { "title": "Search Keyword", "type": "string", "description": "Search top ads by keyword (brand name, product, topicโ€ฆ). Leave empty to browse all top ads.", "default": "" }, "topAdsCountryCode": { "title": "Countries", "uniqueItems": true, "type": "array", "description": "Select one or more countries to filter top ads (leave empty for global results).", "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" ] } }, "topAdsPeriod": { "title": "Time Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Number of days to look back.", "default": "7" }, "topAdsOrderBy": { "title": "Sort Order", "enum": [ "like", "impression", "ctr", "cvr", "play_2s_rate", "play_6s_rate" ], "type": "string", "description": "Sort top ads by metric.", "default": "like" }, "topAdsIndustry": { "title": "Industries", "uniqueItems": true, "type": "array", "description": "Select one or more industries or sub-industries to filter top ads (leave empty for all).", "items": { "type": "string", "enum": [ "10000000000", "10100000000", "10101000000", "10102000000", "10103000000", "10104000000", "10105000000", "10106000000", "10999000000", "11000000000", "11100000000", "11101000000", "11102000000", "11103000000", "11104000000", "11105000000", "11106000000", "11107000000", "11108000000", "11109000000", "11110000000", "11111000000", "11112000000", "11999000000", "12000000000", "12100000000", "12101000000", "12102000000", "12103000000", "12104000000", "12105000000", "12106000000", "12107000000", "12108000000", "12109000000", "12110000000", "12999000000", "13000000000", "13100000000", "13101000000", "13102000000", "13103000000", "13104000000", "13105000000", "13107000000", "13108000000", "13109000000", "13110000000", "13111000000", "13112000000", "13113000000", "13114000000", "13115000000", "13116000000", "13117000000", "13999000000", "14000000000", "14100000000", "14101000000", "14102000000", "14103000000", "14104000000", "14105000000", "14106000000", "14107000000", "14999000000", "15000000000", "15100000000", "15101000000", "15102000000", "15103000000", "15104000000", "15105000000", "15106000000", "15107000000", "15999000000", "16000000000", "16100000000", "16101000000", "16102000000", "16104000000", "16105000000", "16999000000", "17000000000", "17103000000", "17105000000", "17106000000", "17999000000", "18000000000", "18100000000", "18101000000", "18102000000", "18103000000", "18104000000", "18105000000", "18106000000", "18107000000", "18108000000", "18109000000", "18110000000", "18111000000", "18112000000", "18999000000", "19000000000", "19100000000", "19101000000", "19102000000", "19103000000", "19104000000", "19105000000", "19106000000", "19999000000", "20000000000", "20100000000", "20101000000", "20102000000", "20103000000", "20104000000", "20105000000", "20106000000", "20107000000", "20108000000", "20109000000", "20110000000", "20111000000", "20112000000", "20999000000", "21000000000", "21100000000", "21101000000", "21102000000", "21103000000", "21104000000", "21105000000", "21999000000", "22000000000", "22101000000", "22102000000", "22105000000", "22106000000", "22107000000", "22108000000", "22109000000", "22110000000", "22111000000", "22112000000", "22113000000", "22999000000", "23000000000", "23100000000", "23101000000", "23102000000", "23103000000", "23104000000", "23105000000", "23106000000", "23107000000", "23108000000", "23109000000", "23110000000", "23111000000", "23112000000", "23113000000", "23114000000", "23115000000", "23116000000", "23117000000", "23118000000", "23119000000", "23122000000", "23123000000", "23124000000", "23125000000", "23126000000", "23127000000", "23128000000", "23129000000", "23130000000", "23131000000", "23132000000", "23133000000", "23134000000", "23999000000", "24000000000", "24100000000", "24101000000", "24102000000", "24103000000", "24104000000", "24105000000", "24106000000", "24107000000", "24108000000", "24109000000", "24110000000", "24111000000", "24112000000", "24113000000", "24114000000", "24115000000", "24116000000", "24117000000", "24118000000", "24119000000", "24120000000", "24999000000", "25000000000", "25300000000", "25301000000", "25302000000", "25303000000", "25304000000", "25305000000", "25306000000", "25307000000", "25308000000", "25309000000", "25310000000", "25311000000", "25312000000", "25313000000", "25999000000", "26000000000", "26100000000", "26101000000", "26102000000", "26103000000", "26104000000", "26105000000", "26106000000", "26107000000", "26108000000", "26109000000", "26111000000", "26112000000", "26113000000", "26114000000", "26999000000", "27000000000", "27100000000", "27101000000", "27102000000", "27103000000", "27104000000", "27999000000", "28000000000", "28100000000", "28101000000", "29000000000", "29100000000", "29101000000", "29102000000", "29103000000", "29999000000", "30000000000", "30100000000", "30101000000", "30102000000" ], "enumTitles": [ "๐Ÿ“š Education", " โ”” Early Childhood & Preschool", " โ”” Primary & Secondary / K-12", " โ”” Higher Education", " โ”” Overseas Education", " โ”” Vocational Training", " โ”” Language Training", " โ”” Non-academic Training (Hobbies)", " โ”” Other Education", "๐Ÿš— Vehicle & Transportation", " โ”” Automobiles", " โ”” Auto Accessories", " โ”” Auto Services", " โ”” Auto Parts", " โ”” Car Rentals", " โ”” Used Cars", " โ”” Motorcycles", " โ”” Bicycles", " โ”” Electric Scooters", " โ”” Water Vehicles", " โ”” Airplanes", " โ”” 2/3-Wheeled Vehicle Accessories", " โ”” Car Dealerships", " โ”” Other Vehicle & Transportation", "๐Ÿ‘ถ Baby, Kids & Maternity", " โ”” Baby Food", " โ”” Strollers & Cribs", " โ”” Baby Formula", " โ”” Diapers & Baby Wipes", " โ”” Baby Bedding", " โ”” Baby Shoes", " โ”” Toys for Kids", " โ”” Child Car Seats", " โ”” Baby Feeding Supplies", " โ”” Children's Apparel", " โ”” Baby Hygiene Products", " โ”” Other Baby, Kids & Maternity", "๐Ÿ’ฐ Financial Services", " โ”” Commercial Banks", " โ”” Securities", " โ”” Insurance", " โ”” Trusts", " โ”” Guarantees", " โ”” Pawn Shops", " โ”” Funds", " โ”” Credit Bureaus", " โ”” Microfinance Companies", " โ”” Investment Advisory", " โ”” Loan Services", " โ”” Foreign Exchange", " โ”” Precious Metals", " โ”” Third-Party Payments", " โ”” Crowd Funding", " โ”” Cryptocurrencies", " โ”” Credit Cards", " โ”” Other Financial Services", "๐Ÿ’„ Beauty & Personal Care", " โ”” Oral Care", " โ”” Haircare", " โ”” Wig & Hair Styling", " โ”” Skincare", " โ”” Cosmetics", " โ”” Aesthetic Medicine", " โ”” Fragrances & Perfumes", " โ”” Feminine Care", " โ”” Other Beauty & Personal Care", "๐Ÿ“ฑ Tech & Electronics", " โ”” Cell Phones", " โ”” Computers", " โ”” Computer Components", " โ”” Computer Repair", " โ”” Gaming Devices", " โ”” Computer Accessories", " โ”” Network Products", " โ”” Office Equipment", " โ”” Other Tech & Electronics", "๐Ÿ”Œ Appliances", " โ”” Personal Care Appliances", " โ”” Kitchen & Bathroom Appliances", " โ”” Large Appliances", " โ”” Home Appliances", " โ”” Digital Devices", " โ”” Other Appliances", "โœˆ๏ธ Travel", " โ”” Hotels & Accommodation", " โ”” Tours & Attractions", " โ”” Travel Agencies & Services", " โ”” Other Travel", "๐Ÿ  Household Products", " โ”” Storage Products", " โ”” Daily Essentials", " โ”” Glasses & Drinkware", " โ”” Tea Sets", " โ”” Coffee Accessories", " โ”” Kitchen Accessories", " โ”” Cleaning Appliances", " โ”” Tissues & Wet Wipes", " โ”” Laundry", " โ”” Leather Care", " โ”” Cleaning Supplies", " โ”” Toys", " โ”” Pest Control", " โ”” Other Household Products", "๐Ÿพ Pets", " โ”” Petfood", " โ”” Pet Healthcare", " โ”” Pet Household Products", " โ”” Pet Grooming", " โ”” Pet Treats", " โ”” Pet Toys", " โ”” Pet Travel Accessories", " โ”” Other Pets", "๐Ÿ“ฒ Apps", " โ”” Social", " โ”” Audio & Video Players", " โ”” News & Reading", " โ”” Photography", " โ”” Education", " โ”” Online Shopping", " โ”” Financial Services", " โ”” Life & Leisure", " โ”” Travel", " โ”” Health & Fitness", " โ”” Business & Productivity", " โ”” Parenting", " โ”” Utilities", " โ”” Other Apps", "๐Ÿ”จ Home Improvement", " โ”” Interior Design & Decorating", " โ”” Furniture", " โ”” Construction Materials & Lighting", " โ”” Hardware & Electrical", " โ”” Home Decor", " โ”” Power Strips & Socket", " โ”” Other Home Improvement", "๐Ÿ‘— Apparel & Accessories", " โ”” Clothing Accessories", " โ”” Bags", " โ”” Watches", " โ”” Ordinary Jewelry", " โ”” High-end Jewelry", " โ”” Men's Clothing", " โ”” Men's Shoes", " โ”” Women's Clothing", " โ”” Women's Shoes", " โ”” Traditional & Ceremonial Clothing", " โ”” Wearable Tech Devices", " โ”” Other Apparel & Accessories", "๐Ÿ“ฐ News & Entertainment", " โ”” Military", " โ”” Politics", " โ”” Business & Economy", " โ”” Science & Technology", " โ”” Culture & History", " โ”” Charity & Public Welfare", " โ”” Law", " โ”” Environmental Protection", " โ”” Celebrities & Gossip", " โ”” Lifestyle News", " โ”” Live Events", " โ”” Collectables & Antiques", " โ”” TV Drama & Series", " โ”” Anime", " โ”” Astrology", " โ”” Humor", " โ”” Culture & Art", " โ”” TV Variety Shows", " โ”” Reading", " โ”” Movies", " โ”” Beauty & Personal Care", " โ”” Sports & Fitness", " โ”” Food & Cooking", " โ”” Games & Utility Software", " โ”” Car Information", " โ”” General Information", " โ”” E-commerce Information", " โ”” Pet Information", " โ”” Real Estate Information", " โ”” Relationship Information", " โ”” Streaming Site", " โ”” Tourist Information", " โ”” Social Media Account Promotion", " โ”” Other News & Entertainment", "๐Ÿ’ผ Business Services", " โ”” Real Estate & Home Rentals", " โ”” Office Equipment & Supplies", " โ”” Recruitment & Job Searching", " โ”” Constructional Engineering", " โ”” Electronics & Electrical", " โ”” Chemical Materials", " โ”” Machinery & Equipment", " โ”” Franchising", " โ”” Agriculture & Forestry", " โ”” Energy & Environmental Protection", " โ”” Safety & Security", " โ”” Logistics", " โ”” Marketing & Advertising", " โ”” Professional Consultation", " โ”” Exhibition Services", " โ”” Service Outsourcing", " โ”” IT Services", " โ”” Legal Services", " โ”” Auction Services", " โ”” Investment Planning & Management", " โ”” Individual Entrepreneurship", " โ”” Other Business Services", "๐ŸŽฎ Games", " โ”” Hyper-Casual", " โ”” Action", " โ”” Casino", " โ”” Match", " โ”” Puzzle", " โ”” Racing", " โ”” RPG", " โ”” Shooting", " โ”” Simulation", " โ”” Sports", " โ”” Strategy", " โ”” Party", " โ”” Tabletop", " โ”” Kids", " โ”” Other Games", "๐Ÿ›Ž๏ธ Life Services", " โ”” Wedding Photography", " โ”” Photography", " โ”” Dating & Matchmaking", " โ”” Wedding Celebrations", " โ”” Gifts & Flowers", " โ”” Housekeeping", " โ”” Shopping Services", " โ”” Used Good Sales Platforms", " โ”” Gardening", " โ”” Utilities Payments", " โ”” Internet Services", " โ”” Consumer Services", " โ”” Exercise & Fitness", " โ”” Beauty & Personal Care", " โ”” Other Life Services", "๐Ÿ” Food & Beverage", " โ”” Cuisine", " โ”” Food & Fresh Produce", " โ”” Non-alcoholic Beverages", " โ”” Alcoholic Beverages", " โ”” Cooking & Recipes", " โ”” Other Food & Beverage", "โšฝ Sports & Outdoor", " โ”” Outdoor Equipment", " โ”” Sports & Equipment", "๐Ÿฅ Health", " โ”” Medical Services", " โ”” Medical Information", " โ”” Dietary Supplements", " โ”” Medicine", " โ”” Other Health", "๐Ÿ›’ E-Commerce (Non-app)", " โ”” Big Box Retailers", " โ”” Small & Medium E-commerce Platforms", " โ”” Large E-commerce Platforms" ] } }, "topAdsObjective": { "title": "Campaign Objectives", "uniqueItems": true, "type": "array", "description": "Select one or more campaign objectives to filter top ads (leave empty for all objectives).", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "8", "15" ], "enumTitles": [ "๐Ÿ”— Traffic", "๐Ÿ“ฒ App Installs", "๐ŸŽฏ Conversions", "โ–ถ๏ธ Video Views", "๐Ÿ“ก Reach", "๐Ÿ“‹ Lead Generation", "๐Ÿ›๏ธ Product Sales" ] } }, "topAdsLanguage": { "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 ads by language. Leave empty for all languages.", "default": "" }, "topAdsLikeRange": { "title": "Likes Percentile", "enum": [ "", "1", "2", "3", "4", "5" ], "type": "string", "description": "Filter by likes performance percentile. Leave empty for all.", "default": "" }, "topAdsMaxItems": { "title": "Maximum Number of Top Ads", "minimum": 1, "type": "integer", "description": "Maximum number of top ads to return.", "default": 100 }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy for Ads Library mode. Top Ads mode runs without proxy for best performance.", "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 } } } } } } } } } } ```