{ "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Scraper - Creative Center Top Ads", "description": "Scrape the top-performing TikTok ads from Creative Center by country, period, industry, objective and sort order. Get ad copy, brand, CTR, likes, budget tier and direct video links. Add ad details: landing page, comments, shares and the countries the ad ran in. No TikTok account. No browser.", "version": "0.1", "x-build-id": "lZP6G8gpv1Hq7IxX3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hgservices~tiktok-top-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hgservices-tiktok-top-ads-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/hgservices~tiktok-top-ads-scraper/runs": { "post": { "operationId": "runs-sync-hgservices-tiktok-top-ads-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/hgservices~tiktok-top-ads-scraper/run-sync": { "post": { "operationId": "run-sync-hgservices-tiktok-top-ads-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "countries": { "title": "Countries", "type": "array", "description": "Countries whose Top Ads to read. Leave empty for the United States.", "items": { "type": "string", "enum": [ "AR", "AU", "BR", "CA", "CO", "FR", "DE", "ID", "IT", "JP", "MY", "MX", "NL", "PK", "PH", "RO", "SA", "SG", "ZA", "KR", "ES", "SE", "TH", "TR", "AE", "GB", "US", "VN" ], "enumTitles": [ "Argentina", "Australia", "Brazil", "Canada", "Colombia", "France", "Germany", "Indonesia", "Italy", "Japan", "Malaysia", "Mexico", "Netherlands", "Pakistan", "Philippines", "Romania", "Saudi Arabia", "Singapore", "South Africa", "South Korea", "Spain", "Sweden", "Thailand", "Turkey", "United Arab Emirates", "United Kingdom", "United States", "Vietnam" ] } }, "periods": { "title": "Periods", "type": "array", "description": "The ranking windows, in days: 7 for what performs right now, 30 for the monthly top, 180 for long-running winners. Every period selected is read for every country.", "items": { "type": "string", "enum": [ "7", "30", "180" ], "enumTitles": [ "Last 7 days", "Last 30 days", "Last 180 days" ] } }, "objectives": { "title": "Campaign objectives", "type": "array", "description": "Read only ads with these campaign objectives. Leave empty for all objectives. Every objective selected is read for every country and period.", "items": { "type": "string", "enum": [ "traffic", "app_install", "conversions", "video_views", "reach", "lead_generation", "product_sales", "app_promotion" ], "enumTitles": [ "Traffic", "App installs", "Conversions", "Video views", "Reach", "Lead generation", "Product sales", "App promotion" ] } }, "industries": { "title": "Industries", "type": "array", "description": "Read only ads from these industries. A parent industry, marked (all), also includes its sub-industries. Every industry selected is read for every country, period and objective. Leave empty for all industries. API users pass the industry IDs, for example \"25000000000\" for E-commerce & Shopping; the README lists every ID.", "items": { "type": "string", "enum": [ "22000000000", "22102000000", "22101000000", "22107000000", "22108000000", "22109000000", "22106000000", "22999000000", "22112000000", "22105000000", "22113000000", "22110000000", "22111000000", "16000000000", "16105000000", "16104000000", "16101000000", "16102000000", "16999000000", "16100000000", "20000000000", "20101000000", "20110000000", "20104000000", "20106000000", "20109000000", "20107000000", "20102000000", "20105000000", "20999000000", "20111000000", "20103000000", "20100000000", "20108000000", "20112000000", "12000000000", "12104000000", "12108000000", "12100000000", "12102000000", "12110000000", "12105000000", "12107000000", "12109000000", "12103000000", "12999000000", "12101000000", "12106000000", "14000000000", "14105000000", "14104000000", "14107000000", "14106000000", "14101000000", "14100000000", "14999000000", "14103000000", "14102000000", "24000000000", "24108000000", "24118000000", "24105000000", "24103000000", "24104000000", "24109000000", "24114000000", "24107000000", "24116000000", "24120000000", "24119000000", "24117000000", "24111000000", "24106000000", "24112000000", "24101000000", "24999000000", "24113000000", "24100000000", "24102000000", "24110000000", "24115000000", "30000000000", "30100000000", "30102000000", "30101000000", "10000000000", "10100000000", "10102000000", "10105000000", "10106000000", "10999000000", "10103000000", "10101000000", "10104000000", "13000000000", "13100000000", "13108000000", "13117000000", "13115000000", "13116000000", "13112000000", "13107000000", "13104000000", "13102000000", "13110000000", "13111000000", "13109000000", "13999000000", "13105000000", "13113000000", "13101000000", "13114000000", "13103000000", "27000000000", "27103000000", "27104000000", "27100000000", "27101000000", "27102000000", "27999000000", "25000000000", "25301000000", "25302000000", "25300000000", "25313000000", "25303000000", "25999000000", "25311000000", "25304000000", "25306000000", "25305000000", "25307000000", "25308000000", "25309000000", "25310000000", "25312000000", "29000000000", "29102000000", "29101000000", "29100000000", "29103000000", "29999000000", "21000000000", "21102000000", "21101000000", "21103000000", "21104000000", "21100000000", "21999000000", "21105000000", "18000000000", "18106000000", "18110000000", "18104000000", "18101000000", "18102000000", "18105000000", "18108000000", "18109000000", "18999000000", "18112000000", "18100000000", "18103000000", "18107000000", "18111000000", "26000000000", "26114000000", "26112000000", "26102000000", "26113000000", "26108000000", "26104000000", "26105000000", "26111000000", "26999000000", "26101000000", "26106000000", "26107000000", "26109000000", "26103000000", "26100000000", "23000000000", "23113000000", "23114000000", "23122000000", "23102000000", "23126000000", "23108000000", "23105000000", "23111000000", "23116000000", "23104000000", "23128000000", "23107000000", "23124000000", "23125000000", "23127000000", "23115000000", "23106000000", "23109000000", "23110000000", "23100000000", "23119000000", "23999000000", "23129000000", "23101000000", "23118000000", "23130000000", "23131000000", "23103000000", "23134000000", "23123000000", "23132000000", "23112000000", "23117000000", "23133000000", "19000000000", "19999000000", "19103000000", "19101000000", "19102000000", "19105000000", "19106000000", "19104000000", "19100000000", "28000000000", "28100000000", "28101000000", "15000000000", "15100000000", "15105000000", "15103000000", "15101000000", "15102000000", "15104000000", "15106000000", "15107000000", "15999000000", "17000000000", "17103000000", "17999000000", "17105000000", "17106000000", "11000000000", "11111000000", "11110000000", "11101000000", "11103000000", "11102000000", "11100000000", "11107000000", "11112000000", "11104000000", "11108000000", "11106000000", "11999000000", "11105000000", "11109000000" ], "enumTitles": [ "Apparel & Accessories (all)", "Apparel & Accessories › Bags", "Apparel & Accessories › Clothing Accessories", "Apparel & Accessories › High-end Jewelry", "Apparel & Accessories › Men's Clothing", "Apparel & Accessories › Men's Shoes", "Apparel & Accessories › Ordinary Jewelry", "Apparel & Accessories › Other Apparel & Accessories", "Apparel & Accessories › Traditional & Ceremonial Clothing", "Apparel & Accessories › Watches", "Apparel & Accessories › Wearable Tech Devices", "Apparel & Accessories › Women's Clothing", "Apparel & Accessories › Women's Shoes", "Appliances (all)", "Appliances › Digital Devices", "Appliances › Home Appliances", "Appliances › Kitchen & Bathroom Appliances", "Appliances › Large Appliances", "Appliances › Other Appliances", "Appliances › Personal Care Appliances", "Apps (all)", "Apps › Audio & Video Players", "Apps › Business & Productivity", "Apps › Education", "Apps › Financial Services", "Apps › Health & Fitness", "Apps › Life & Leisure", "Apps › News & Reading", "Apps › Online Shopping", "Apps › Other Apps", "Apps › Parenting", "Apps › Photography", "Apps › Social", "Apps › Travel", "Apps › Utilities", "Baby, Kids & Maternity (all)", "Baby, Kids & Maternity › Baby Bedding", "Baby, Kids & Maternity › Baby Feeding Supplies", "Baby, Kids & Maternity › Baby Food", "Baby, Kids & Maternity › Baby Formula", "Baby, Kids & Maternity › Baby Hygiene Products", "Baby, Kids & Maternity › Baby Shoes", "Baby, Kids & Maternity › Child Car Seats", "Baby, Kids & Maternity › Children's Apparel", "Baby, Kids & Maternity › Diapers & Baby Wipes", "Baby, Kids & Maternity › Other Baby, Kids & Maternity", "Baby, Kids & Maternity › Strollers & Cribs", "Baby, Kids & Maternity › Toys for Kids", "Beauty & Personal Care (all)", "Beauty & Personal Care › Aesthetic Medicine", "Beauty & Personal Care › Cosmetics", "Beauty & Personal Care › Feminine Care", "Beauty & Personal Care › Fragrances & Perfumes", "Beauty & Personal Care › Haircare", "Beauty & Personal Care › Oral Care", "Beauty & Personal Care › Other Beauty & Personal Care", "Beauty & Personal Care › Skincare", "Beauty & Personal Care › Wig & Hair Styling", "Business Services (all)", "Business Services › Agriculture, Forestry, Animal Husbandry & Fishing", "Business Services › Auction Services", "Business Services › Chemical Materials", "Business Services › Constructional Engineering", "Business Services › Electronics & Electrical", "Business Services › Energy Conservation & Environmental Protection", "Business Services › Exhibition Services", "Business Services › Franchising", "Business Services › IT Services", "Business Services › Individual Entrepreneurship", "Business Services › Investment Planning & Management", "Business Services › Legal Services", "Business Services › Logistics", "Business Services › Machinery & Equipment", "Business Services › Marketing & Advertising", "Business Services › Office Equipment & Supplies", "Business Services › Other Business Services", "Business Services › Professional Consultation", "Business Services › Real Estate & Home Rentals", "Business Services › Recruitment & Job Searching", "Business Services › Safety & Security", "Business Services › Service Outsourcing", "E-Commerce (Non-app) (all)", "E-Commerce (Non-app) › Big Box Retailers", "E-Commerce (Non-app) › Large E-commerce Platforms", "E-Commerce (Non-app) › Small & Medium-sized E-commerce Platforms", "Education (all)", "Education › Early Childhood & Preschool Education", "Education › Higher Education", "Education › Language Training", "Education › Non-academic Training (Hobbies)", "Education › Other Education", "Education › Overseas Education", "Education › Primary & Secondary Education & K-12", "Education › Vocational Training", "Financial Services (all)", "Financial Services › Commercial Banks", "Financial Services › Credit Bureaus", "Financial Services › Credit Cards", "Financial Services › Crowd Funding", "Financial Services › Cryptocurrencies", "Financial Services › Foreign Exchange Transactions", "Financial Services › Funds", "Financial Services › Guarantees", "Financial Services › Insurance", "Financial Services › Investment Advisory", "Financial Services › Loan Services", "Financial Services › Microfinance Companies", "Financial Services › Other Financial Services", "Financial Services › Pawn Shops", "Financial Services › Precious Metals", "Financial Services › Securities", "Financial Services › Third-Party Payments", "Financial Services › Trusts", "Food & Beverage (all)", "Food & Beverage › Alcoholic Beverages", "Food & Beverage › Cooking & Recipes", "Food & Beverage › Cuisine", "Food & Beverage › Food & Fresh Produce", "Food & Beverage › Non-alcoholic Beverages", "Food & Beverage › Other Food & Beverage", "Games (all)", "Games › Action", "Games › Casino", "Games › Hyper-Casual", "Games › Kids", "Games › Match", "Games › Other", "Games › Party", "Games › Puzzle", "Games › RPG", "Games › Racing", "Games › Shooting", "Games › Simulation", "Games › Sports", "Games › Strategy", "Games › Tabletop", "Health (all)", "Health › Dietary Supplements", "Health › Medical Information", "Health › Medical Services", "Health › Medicine", "Health › Other Health", "Home Improvement (all)", "Home Improvement › Construction Materials & Lighting", "Home Improvement › Furniture", "Home Improvement › Hardware & Electrical", "Home Improvement › Home Decor", "Home Improvement › Interior Design & Decorating Services", "Home Improvement › Other Home Improvement", "Home Improvement › Power Strips & Socket", "Household Products (all)", "Household Products › Cleaning Appliances", "Household Products › Cleaning Supplies", "Household Products › Coffee Accessories", "Household Products › Daily Essentials", "Household Products › Glasses & Drinkware", "Household Products › Kitchen Accessories", "Household Products › Laundry", "Household Products › Leather Care", "Household Products › Other Household Products", "Household Products › Pest Control", "Household Products › Storage Products", "Household Products › Tea Sets", "Household Products › Tissues & Wet Wipes", "Household Products › Toys", "Life Services (all)", "Life Services › Beauty & Personal Care", "Life Services › Consumer Services", "Life Services › Dating & Matchmaking Services", "Life Services › Exercise & Fitness", "Life Services › Gardening", "Life Services › Gifts & Flowers", "Life Services › Housekeeping", "Life Services › Internet Services", "Life Services › Other Life Services", "Life Services › Photography", "Life Services › Shopping Services", "Life Services › Used Good Sales Platforms", "Life Services › Utilities Payments", "Life Services › Wedding Celebrations", "Life Services › Wedding Photography", "News & Entertainment (all)", "News & Entertainment › Anime", "News & Entertainment › Astrology", "News & Entertainment › Beauty & Personal Care", "News & Entertainment › Business & Economy", "News & Entertainment › Car Information", "News & Entertainment › Celebrities & Gossip", "News & Entertainment › Charity & Public Welfare", "News & Entertainment › Collectables & Antiques", "News & Entertainment › Culture & Art", "News & Entertainment › Culture & History", "News & Entertainment › E-commerce Information", "News & Entertainment › Environmental Protection", "News & Entertainment › Food & Cooking", "News & Entertainment › Games & Utility Software", "News & Entertainment › General Information", "News & Entertainment › Humor", "News & Entertainment › Law", "News & Entertainment › Lifestyle News", "News & Entertainment › Live Events", "News & Entertainment › Military", "News & Entertainment › Movies", "News & Entertainment › Other News & Entertainment", "News & Entertainment › Pet Information", "News & Entertainment › Politics", "News & Entertainment › Reading", "News & Entertainment › Real Estate Information", "News & Entertainment › Relationship Information", "News & Entertainment › Science & Technology", "News & Entertainment › Social Media Account Promotion", "News & Entertainment › Sports & Fitness", "News & Entertainment › Streaming Site", "News & Entertainment › TV Drama & Series", "News & Entertainment › TV Variety Shows", "News & Entertainment › Tourist Information", "Pets (all)", "Pets › Other Pets", "Pets › Pet Grooming", "Pets › Pet Healthcare", "Pets › Pet Household Products", "Pets › Pet Toys", "Pets › Pet Travel Accessories", "Pets › Pet Treats", "Pets › Petfood", "Sports & Outdoor (all)", "Sports & Outdoor › Outdoor Equipment", "Sports & Outdoor › Sports & Equipment", "Tech & Electronics (all)", "Tech & Electronics › Cell Phones", "Tech & Electronics › Computer Accessories", "Tech & Electronics › Computer Repair", "Tech & Electronics › Computers", "Tech & Electronics › Computers Components", "Tech & Electronics › Gaming Devices", "Tech & Electronics › Network Products", "Tech & Electronics › Office Equipment", "Tech & Electronics › Other Tech & Electronics", "Travel (all)", "Travel › Hotels & Accommodation", "Travel › Other Travel", "Travel › Tours & Attractions", "Travel › Travel Agencies & Services", "Vehicle & Transportation (all)", "Vehicle & Transportation › Accessories for 2/3-Wheeled Vehicles", "Vehicle & Transportation › Airplanes", "Vehicle & Transportation › Auto Accessories", "Vehicle & Transportation › Auto Parts", "Vehicle & Transportation › Auto Services", "Vehicle & Transportation › Automobiles", "Vehicle & Transportation › Bicycles", "Vehicle & Transportation › Car Dealerships", "Vehicle & Transportation › Car Rentals", "Vehicle & Transportation › Electric Scooters", "Vehicle & Transportation › Motorcycles", "Vehicle & Transportation › Other Vehicle & Transportation", "Vehicle & Transportation › Used Cars", "Vehicle & Transportation › Water Vehicles" ] } }, "sortBy": { "title": "Sort by", "enum": [ "for_you", "ctr", "likes", "impressions", "conversions" ], "type": "string", "description": "How TikTok ranks the ads. For You is TikTok's recommended mix, CTR the best click-through rank, Likes the most engaging, Impressions the widest reach, Conversions the best converting. The first 20 ads of each combination come in TikTok's order. The ads after them come in the order of the CTR rank or the likes when you sort by these, and in the order that the Actor found them for the other sorts.", "default": "for_you" }, "topAdsOnly": { "title": "Only TikTok's top 20", "type": "boolean", "description": "Read only the first 20 ads that TikTok ranks for each combination. Faster: one request per combination. Off: the Actor splits each combination by industry and objective and reads all its ads: about one request for each 6 ads, a few seconds each.", "default": false }, "includeAdDetails": { "title": "Add ad details", "type": "boolean", "description": "Fetch the detail page of each ad too: landing page, comments, shares, the countries the ad ran in and all its objectives. Slower: one more request per ad.", "default": false }, "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Stop after this many ads, over all combinations. For example, the US has about 25 ads for 7 days, 140 for 30 days and more than 1,000 for 180 days.", "default": 1000 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }