{ "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.0", "x-build-id": "UWOr55DoVRVdNvdZ0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/data_xplorer~tiktok-ads-library-pay-per-event/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-data_xplorer-tiktok-ads-library-pay-per-event", "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-library-pay-per-event/runs": { "post": { "operationId": "runs-sync-data_xplorer-tiktok-ads-library-pay-per-event", "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-library-pay-per-event/run-sync": { "post": { "operationId": "run-sync-data_xplorer-tiktok-ads-library-pay-per-event", "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": true }, "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 } } } } } } } } } }