{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Spy", "description": "Scrape ads from TikTok Ads Library (EU/EEA + UK + Switzerland + Turkey) and Creative Center Top Ads (global, includes US). Filter by region, advertiser, date range, industry, objective. Optional video download and landing-page resolution.", "version": "0.0", "x-build-id": "InyQeZlin5uAbMyQa" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~tiktok-ads-spy/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-tiktok-ads-spy", "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/lurkapi~tiktok-ads-spy/runs": { "post": { "operationId": "runs-sync-lurkapi-tiktok-ads-spy", "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/lurkapi~tiktok-ads-spy/run-sync": { "post": { "operationId": "run-sync-lurkapi-tiktok-ads-spy", "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": { "source": { "title": "Ad source", "enum": [ "adsLibrary", "creativeCenter" ], "type": "string", "description": "Which TikTok ad surface to scrape. Ads Library is TikTok's EU transparency database (EU/EEA + UK + Switzerland + Turkey only). Creative Center Top Ads is global and includes the US.", "default": "creativeCenter" }, "ccKeyword": { "title": "Keywords", "type": "array", "description": "One or more search terms. Each runs as a separate search. Combined with Countries, you get one search per (keyword × country) pair. Matches ad title text. Outer quotes are stripped automatically.", "items": { "type": "string" } }, "ccCountry": { "title": "Countries", "type": "array", "description": "Pick one or more countries. The actor runs a separate search per country. Leave empty to default to United States.", "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" ] } }, "ccPeriod": { "title": "Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window for the Top Ads list.", "default": "30" }, "ccObjective": { "title": "Campaign objective", "enum": [ "", "1", "2", "3", "4", "5", "8", "15" ], "type": "string", "description": "Filter by the advertiser's campaign objective.", "default": "" }, "ccLanguage": { "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 by the language of the ad creative.", "default": "" }, "ccIndustry": { "title": "Industry", "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", "24120000000", "24119000000", "24116000000", "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", "25305000000", "25306000000", "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", "23133000000", "23112000000", "23117000000", "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" ], "type": "string", "description": "Filter Top Ads to a single industry. Pick a top-level category like 'Apparel & Accessories' to include every sub-industry below it, or pick a specific sub-industry to narrow further.", "default": "" }, "ccOrderBy": { "title": "Sort order", "enum": [ "for_you", "ctr", "like", "play_six_rate", "play_two_five_rate" ], "type": "string", "description": "How to order the Top Ads list.", "default": "for_you" }, "alibQuery": { "title": "Keywords or advertiser names", "type": "array", "description": "One or more search terms. Each runs as a separate search. Combined with Regions, you get one search per (keyword × region) pair. Outer quotes are stripped automatically (don't wrap terms in quotes unless you want TikTok's exact-match behavior, which usually returns 0 results).", "items": { "type": "string" } }, "alibQueryType": { "title": "Search by", "enum": [ "1", "2" ], "type": "string", "description": "What the search text matches against.", "default": "1" }, "alibAdvBizIds": { "title": "Advertiser business IDs", "type": "string", "description": "Optional comma-separated TikTok business IDs to refine results when the advertiser name above matches several brands. Use together with the advertiser name and set 'Search by' to 'Advertiser name'. The business ID alone is ignored by TikTok." }, "alibRegion": { "title": "Countries", "type": "array", "description": "Pick one or more EU/EEA + UK + Switzerland + Turkey countries. The actor runs a separate search per country. Leave empty to default to United Kingdom.", "items": { "type": "string", "enum": [ "AT", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB", "GR", "HR", "HU", "IE", "IS", "IT", "LI", "LT", "LU", "LV", "MT", "NL", "NO", "PL", "PT", "RO", "SE", "SI", "SK", "TR" ], "enumTitles": [ "Austria", "Belgium", "Bulgaria", "Switzerland", "Cyprus", "Czechia", "Germany", "Denmark", "Estonia", "Spain", "Finland", "France", "United Kingdom", "Greece", "Croatia", "Hungary", "Ireland", "Iceland", "Italy", "Liechtenstein", "Lithuania", "Luxembourg", "Latvia", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Sweden", "Slovenia", "Slovakia", "Turkey" ] } }, "alibPeriod": { "title": "Date range", "enum": [ "7", "30", "90", "180", "365", "custom" ], "type": "string", "description": "Time window for the ad's last-shown date. Choose 'Custom' to enter explicit start and end dates below.", "default": "30" }, "alibStartDate": { "title": "Start date (custom range)", "type": "string", "description": "Only used when Date range is set to Custom. ISO date like 2025-01-15." }, "alibEndDate": { "title": "End date (custom range)", "type": "string", "description": "Only used when Date range is set to Custom. ISO date like 2025-12-31." }, "alibSortType": { "title": "Sort order", "enum": [ "last_shown_date,desc", "first_shown_date,desc", "first_shown_date,asc", "last_shown_date,asc" ], "type": "string", "description": "How to order the Ads Library results.", "default": "last_shown_date,desc" }, "alibAdIds": { "title": "Ad IDs (optional)", "type": "array", "description": "Scrape specific Ads Library ads by ID. Each ID returns the full ad detail (advertiser name, dates, video URL, external link, call to action, advertising objective). One per line.", "items": { "type": "string" } }, "alibSkipAdIds": { "title": "Ad IDs to skip (optional)", "type": "array", "description": "Ad IDs already scraped in a previous run. The actor skips these before fetching, so you don't pay twice for the same ad. Useful for scheduled or incremental runs.", "items": { "type": "string" } }, "maxAds": { "title": "Max ads per search", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on ads returned per filter combination. Specific ad ID inputs always return one each, regardless of this cap.", "default": 100 }, "outputVideoDownload": { "title": "Download video ($)", "type": "boolean", "description": "Saves each ad's MP4 to your Apify key-value store. Adds savedVideoKey to the row. Billed at $0.003 per successful download.", "default": false }, "outputLandingPage": { "title": "Resolve landing page ($)", "type": "boolean", "description": "Follows the ad's click tracker URL to find the final merchant landing page. Ads Library only. Implies 'Fetch per-ad details' (the destination link is only on the detail endpoint). Billed at $0.001 per successful resolution.", "default": false }, "outputFetchDetails": { "title": "Enrich with ad details ($)", "type": "boolean", "description": "Adds extra fields to every row: call-to-action button text, advertising objective, destination URL, voiceover yes/no, comment and share counts, every country the ad ran in, campaign keywords, and more. Useful for deeper competitor analysis and creative reviews. Billed at $0.001 per ad enriched. Only successful enrichments are charged.", "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 } } }, "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 } } } } } } } } } }