{ "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Scraper & API: Creative Center Ad Spy", "description": "TikTok Creative Center top ads by country: video, brand, ad text, likes, CTR score, objective, industry, landing page, target countries and second-by-second viewer retention. The whole ranking, not just 20. Keyword filter, new-ad alerts. No login.", "version": "0.1", "x-build-id": "ghdNH017lQisBVaSN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/s_actors~tiktok-top-ads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-s_actors-tiktok-top-ads", "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/s_actors~tiktok-top-ads/runs": { "post": { "operationId": "runs-sync-s_actors-tiktok-top-ads", "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/s_actors~tiktok-top-ads/run-sync": { "post": { "operationId": "run-sync-s_actors-tiktok-top-ads", "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 you want. TikTok Creative Center ranks top ads in these 28 countries; each country is collected separately.", "items": { "type": "string", "enum": [ "US", "GB", "DE", "FR", "IT", "ES", "NL", "SE", "RO", "TR", "AE", "SA", "PK", "ZA", "CA", "MX", "BR", "AR", "CO", "AU", "JP", "KR", "ID", "MY", "PH", "SG", "TH", "VN" ], "enumTitles": [ "United States (US)", "United Kingdom (GB)", "Germany (DE)", "France (FR)", "Italy (IT)", "Spain (ES)", "Netherlands (NL)", "Sweden (SE)", "Romania (RO)", "Turkey (TR)", "United Arab Emirates (AE)", "Saudi Arabia (SA)", "Pakistan (PK)", "South Africa (ZA)", "Canada (CA)", "Mexico (MX)", "Brazil (BR)", "Argentina (AR)", "Colombia (CO)", "Australia (AU)", "Japan (JP)", "South Korea (KR)", "Indonesia (ID)", "Malaysia (MY)", "Philippines (PH)", "Singapore (SG)", "Thailand (TH)", "Vietnam (VN)" ] }, "default": [ "US" ] }, "period": { "title": "📅 Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Ads that ran in the last 7, 30 or 180 days. TikTok ranks about 30-50 (7 days), 100-160 (30 days) or a few thousand (180 days) ads per country.", "default": "30" }, "maxAdsPerCountry": { "title": "🔢 Max ads per country", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop after this many ads per country. Above the size of TikTok's ranking you get the whole ranking.", "default": 100 }, "sortBy": { "title": "↕️ Sort by", "enum": [ "for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like" ], "type": "string", "description": "TikTok's ranking to put first. Its top 20 come in TikTok's exact order (column rank), the rest follow by likes (by CTR score for CTR).", "default": "for_you" }, "keywords": { "title": "🔎 Keywords", "type": "array", "description": "Only ads whose brand, ad text or landing page contain one of these words (a competitor's brand or domain, a product). TikTok's own search needs a login, so the Actor reads the whole ranking and filters it. Landing pages are searched only with Ad details on.", "items": { "type": "string" } }, "industries": { "title": "🏷️ Industries", "type": "array", "description": "Only ads of these industries. Empty = all industries.", "items": { "type": "string", "enum": [ "Education", "Vehicle & Transportation", "Baby, Kids & Maternity", "Financial Services", "Beauty & Personal Care", "Tech & Electronics", "Appliances", "Travel", "Household Products", "Pets", "Apps", "Home Improvement", "Apparel & Accessories", "News & Entertainment", "Business Services", "Games", "Life Services", "Food & Beverage", "Sports & Outdoor", "Health", "E-Commerce (Non-app)" ] } }, "objectives": { "title": "🎯 Campaign objectives", "type": "array", "description": "Only ads of these campaign objectives (Traffic, Conversions, App Installs...). Empty = all.", "items": { "type": "string", "enum": [ "Traffic", "App Installs", "Conversions", "Video Views", "Reach", "Lead Generation", "Product Sales", "App Promotion" ] } }, "adFormat": { "title": "🎬 Ad format", "enum": [ "all", "spark", "nonSpark" ], "type": "string", "description": "Spark Ads are organic TikTok posts the advertiser boosted (often creator UGC).", "default": "all" }, "adLanguage": { "title": "🗣️ Ad language", "enum": [ "en", "es", "pt", "fr", "de", "it", "nl", "ro", "ar", "ja", "ko", "zh-Hant", "id", "ms", "th", "vi" ], "type": "string", "description": "Only ads in this language. Empty = all languages." }, "includeDetails": { "title": "📊 Ad details and retention curve", "type": "boolean", "description": "Adds the landing page and its domain, every country the ad targets, comments, shares, the share of viewers still watching at 2 and 6 seconds, average seconds watched and the second-by-second retention curve. Charged as a separate event per ad.", "default": true }, "onlyNew": { "title": "🔔 Only new ads", "type": "boolean", "description": "For scheduled runs (save the input as a task and add a schedule). The first run returns the whole ranking and remembers it; every later run returns only ads that were not in it before. Without it, every row still has isNew.", "default": false }, "monitorName": { "title": "🏷️ Monitor name", "type": "string", "description": "Name of the memory used by isNew and Only new ads. Use a different name for each task.", "default": "default" }, "maxConcurrency": { "title": "⚡ Parallel requests", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many requests to TikTok run at the same time.", "default": 5 }, "proxyConfiguration": { "title": "🛡️ Proxy", "type": "object", "description": "Requests go direct first and switch to Apify datacenter proxies when TikTok refuses them. The default works for most runs.", "default": { "useApifyProxy": true } }, "debugLog": { "title": "🐞 Debug log", "type": "boolean", "description": "Log every retried request (for troubleshooting).", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "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 } } } } } } } } } }