{ "openapi": "3.0.1", "info": { "title": "TikTok Top Ads Leaderboard - 122 Markets & Metrics", "description": "Collect TikTok Creative Center Top Ads across 122 markets with 258 industries, 7 rankings, landing pages, retention curves, and Spotlight. No login or cookies; sweeps past TikTok's 20-ad board up to 500 unique ads.", "version": "1.0", "x-build-id": "4bew8UtrkUN8gbe80" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nimbryxo-studio~tiktok-top-ads-leaderboard-by-country/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nimbryxo-studio-tiktok-top-ads-leaderboard-by-country", "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/nimbryxo-studio~tiktok-top-ads-leaderboard-by-country/runs": { "post": { "operationId": "runs-sync-nimbryxo-studio-tiktok-top-ads-leaderboard-by-country", "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/nimbryxo-studio~tiktok-top-ads-leaderboard-by-country/run-sync": { "post": { "operationId": "run-sync-nimbryxo-studio-tiktok-top-ads-leaderboard-by-country", "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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "leaderboard", "spotlight", "byAdIds" ], "type": "string", "description": "Choose the Top Ads leaderboard, TikTok's handpicked Spotlight, or refresh specific ad IDs.", "default": "leaderboard" }, "country": { "title": "Country", "enum": [ "", "AL", "DZ", "AO", "AR", "AM", "AU", "AT", "AZ", "BH", "BD", "BY", "BE", "BO", "BA", "BW", "BR", "BN", "BG", "KH", "CM", "CA", "CL", "CO", "CR", "CI", "HR", "CY", "CZ", "DK", "DO", "EC", "EG", "SV", "EE", "ET", "FI", "FR", "GE", "DE", "GH", "GR", "GT", "JO", "HN", "HK", "HU", "IN", "ID", "IQ", "IE", "IL", "IT", "JM", "JP", "KZ", "KE", "KW", "KG", "LA", "LV", "LB", "LY", "MY", "MV", "MU", "MX", "MD", "MN", "ME", "MA", "MZ", "MM", "NA", "NL", "NZ", "NI", "NG", "MK", "NO", "OM", "PK", "PS", "PA", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "LT", "RO", "SA", "SN", "RS", "SG", "SK", "SI", "ZA", "KR", "ES", "LK", "SD", "SE", "CH", "TW", "TJ", "TZ", "TH", "TT", "TN", "TR", "UG", "AE", "GB", "US", "UY", "VE", "VN", "YE", "ZM", "ZW" ], "type": "string", "description": "122 supported markets. All countries reads multiple market boards and merges the results; it uses more requests.", "default": "US" }, "period": { "title": "Time period", "enum": [ "7", "30", "180" ], "type": "string", "description": "The trailing window TikTok ranks over.", "default": "30" }, "industry": { "title": "Industry", "enum": [ "", "label_22000000000", "label_22102000000", "label_22101000000", "label_22107000000", "label_22108000000", "label_22109000000", "label_22106000000", "label_22999000000", "label_22112000000", "label_22105000000", "label_22113000000", "label_22110000000", "label_22111000000", "label_16000000000", "label_16105000000", "label_16104000000", "label_16101000000", "label_16102000000", "label_16999000000", "label_16100000000", "label_20000000000", "label_20101000000", "label_20110000000", "label_20104000000", "label_20106000000", "label_20109000000", "label_20107000000", "label_20102000000", "label_20105000000", "label_20999000000", "label_20111000000", "label_20103000000", "label_20100000000", "label_20108000000", "label_20112000000", "label_12000000000", "label_12104000000", "label_12108000000", "label_12100000000", "label_12102000000", "label_12110000000", "label_12105000000", "label_12107000000", "label_12109000000", "label_12103000000", "label_12999000000", "label_12101000000", "label_12106000000", "label_14000000000", "label_14105000000", "label_14104000000", "label_14107000000", "label_14106000000", "label_14101000000", "label_14100000000", "label_14999000000", "label_14103000000", "label_14102000000", "label_24000000000", "label_24108000000", "label_24118000000", "label_24105000000", "label_24103000000", "label_24104000000", "label_24109000000", "label_24114000000", "label_24107000000", "label_24120000000", "label_24119000000", "label_24116000000", "label_24117000000", "label_24111000000", "label_24106000000", "label_24112000000", "label_24101000000", "label_24999000000", "label_24113000000", "label_24100000000", "label_24102000000", "label_24110000000", "label_24115000000", "label_30000000000", "label_30100000000", "label_30102000000", "label_30101000000", "label_10000000000", "label_10100000000", "label_10102000000", "label_10105000000", "label_10106000000", "label_10999000000", "label_10103000000", "label_10101000000", "label_10104000000", "label_13000000000", "label_13100000000", "label_13108000000", "label_13117000000", "label_13115000000", "label_13116000000", "label_13112000000", "label_13107000000", "label_13104000000", "label_13102000000", "label_13110000000", "label_13111000000", "label_13109000000", "label_13999000000", "label_13105000000", "label_13113000000", "label_13101000000", "label_13114000000", "label_13103000000", "label_27000000000", "label_27103000000", "label_27104000000", "label_27100000000", "label_27101000000", "label_27102000000", "label_27999000000", "label_25000000000", "label_25301000000", "label_25302000000", "label_25300000000", "label_25313000000", "label_25303000000", "label_25999000000", "label_25311000000", "label_25304000000", "label_25305000000", "label_25306000000", "label_25307000000", "label_25308000000", "label_25309000000", "label_25310000000", "label_25312000000", "label_29000000000", "label_29102000000", "label_29101000000", "label_29100000000", "label_29103000000", "label_29999000000", "label_21000000000", "label_21102000000", "label_21101000000", "label_21103000000", "label_21104000000", "label_21100000000", "label_21999000000", "label_21105000000", "label_18000000000", "label_18106000000", "label_18110000000", "label_18104000000", "label_18101000000", "label_18102000000", "label_18105000000", "label_18108000000", "label_18109000000", "label_18999000000", "label_18112000000", "label_18100000000", "label_18103000000", "label_18107000000", "label_18111000000", "label_26000000000", "label_26114000000", "label_26112000000", "label_26102000000", "label_26113000000", "label_26108000000", "label_26104000000", "label_26105000000", "label_26111000000", "label_26999000000", "label_26101000000", "label_26106000000", "label_26107000000", "label_26109000000", "label_26103000000", "label_26100000000", "label_23000000000", "label_23113000000", "label_23114000000", "label_23122000000", "label_23102000000", "label_23126000000", "label_23108000000", "label_23105000000", "label_23111000000", "label_23116000000", "label_23104000000", "label_23128000000", "label_23107000000", "label_23124000000", "label_23125000000", "label_23127000000", "label_23115000000", "label_23106000000", "label_23109000000", "label_23110000000", "label_23100000000", "label_23119000000", "label_23999000000", "label_23129000000", "label_23101000000", "label_23118000000", "label_23130000000", "label_23131000000", "label_23103000000", "label_23134000000", "label_23123000000", "label_23132000000", "label_23133000000", "label_23112000000", "label_23117000000", "label_19000000000", "label_19999000000", "label_19103000000", "label_19101000000", "label_19102000000", "label_19105000000", "label_19106000000", "label_19104000000", "label_19100000000", "label_28000000000", "label_28100000000", "label_28101000000", "label_15000000000", "label_15100000000", "label_15105000000", "label_15103000000", "label_15101000000", "label_15102000000", "label_15104000000", "label_15106000000", "label_15107000000", "label_15999000000", "label_17000000000", "label_17103000000", "label_17999000000", "label_17105000000", "label_17106000000", "label_11000000000", "label_11111000000", "label_11110000000", "label_11101000000", "label_11103000000", "label_11102000000", "label_11100000000", "label_11107000000", "label_11112000000", "label_11104000000", "label_11108000000", "label_11106000000", "label_11999000000", "label_11105000000", "label_11109000000" ], "type": "string", "description": "TikTok's industry taxonomy. Child categories are shown under their parent.", "default": "" }, "objective": { "title": "Campaign objective", "enum": [ "", "campaign_objective_traffic", "campaign_objective_app_installs", "campaign_objective_conversion", "campaign_objective_video_views", "campaign_objective_reach", "campaign_objective_lead_generation", "campaign_objective_product_sales", "campaign_objective_app_promotion" ], "type": "string", "description": "Campaign objective as TikTok labels it.", "default": "" }, "language": { "title": "Ad language", "enum": [ "", "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko", "uk" ], "type": "string", "description": "Language of the ad copy.", "default": "" }, "adFormat": { "title": "Ad format", "enum": [ "", "1", "2" ], "type": "string", "description": "Spark ads are boosted organic posts; Non-Spark ads are regular in-feed ads.", "default": "" }, "likeTier": { "title": "Like percentile", "enum": [ "", "1", "2", "3", "4", "5" ], "type": "string", "description": "TikTok's like-percentile band; Top 1-20% is the highest.", "default": "" }, "orderBy": { "title": "Sort by", "enum": [ "for_you", "impression", "ctr", "play_2s_rate", "play_6s_rate", "cvr", "like" ], "type": "string", "description": "TikTok's ranking. CTR and Likes are sorted highest-first locally.", "default": "for_you" }, "maxItems": { "title": "Maximum ads", "minimum": 0, "maximum": 500, "type": "integer", "description": "Maximum unique ads to deliver (0-500). TikTok exposes 20 per board; enable Sweep to read more boards.", "default": 30 }, "sweep": { "title": "Sweep to fill", "type": "boolean", "description": "Read more filter combinations to get past TikTok's 20-ad board. Turn off to get exactly one board.", "default": true }, "includeDetails": { "title": "Include ad details", "type": "boolean", "description": "Add landing page, target countries, comments, shares, and source (one extra request per ad).", "default": true }, "includeKeyframes": { "title": "Include retention curve", "type": "boolean", "description": "Add the per-second retention curve (one extra request per ad).", "default": false }, "adIds": { "title": "Specific ad IDs", "type": "array", "description": "Ad IDs or Creative Center URLs to refresh. Used only in 'Specific ads' mode.", "items": { "type": "string" }, "default": [] } } }, "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 } } } } } } } } } }