{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library & Top Ads Scraper — Targeting, Advertisers", "description": "TikTok ads from the Ad Library (EU, EEA, UK, Switzerland, Turkey): targeting, reach by country, age and gender, who paid, landing page. One-row-per-advertiser summaries, new-ads monitoring, and Creative Center Top Ads with likes, CTR rank and retention curves. No login.", "version": "0.1", "x-build-id": "iKxkmXGuh22Yfdc4Q" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/foxlabs~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-foxlabs-tiktok-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/foxlabs~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-foxlabs-tiktok-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/foxlabs~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-foxlabs-tiktok-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": { "mode": { "title": "What to scrape", "enum": [ "library", "topAds" ], "type": "string", "description": "**Ad Library**: every ad shown in the EU, EEA, Switzerland, the UK and Turkey, searchable by keyword or advertiser, with targeting, reach by country, age and gender, who paid and the landing page. **Top Ads**: TikTok Creative Center's best-performing ads in 28 countries, with likes, CTR rank, video and (optionally) retention and CTR curves.", "default": "library" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords (searched in ad text and advertiser names), advertiser names, or library.tiktok.com links (a search, an advertiser or one ad). Each line is one search. Leave empty to list the ads shown in the chosen countries and period (TikTok lists up to 5,000) — combine with \"Sort by: reach\" to find the biggest advertisers.", "items": { "type": "string" } }, "searchBy": { "title": "Search terms are", "enum": [ "keyword", "advertiser" ], "type": "string", "description": "**Keywords** match ad text and advertiser names. **Advertiser names** are matched to TikTok's advertiser list and return only that advertiser's ads: the exact name wins, otherwise the suggested advertiser with the most ads in the period (every candidate and its ad count is in the SOURCE_REPORT).", "default": "keyword" }, "countries": { "title": "Countries", "type": "array", "description": "Where the ads were shown. The library covers the EU, EEA, Switzerland, the UK and Turkey only (TikTok publishes it under the EU Digital Services Act). Leave empty or pick \"All covered countries\".", "items": { "type": "string", "enum": [ "all", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "CH", "TR", "GB" ], "enumTitles": [ "All covered countries", "Austria", "Belgium", "Bulgaria", "Croatia", "Cyprus", "Czech Republic", "Denmark", "Estonia", "Finland", "France", "Germany", "Greece", "Hungary", "Iceland", "Ireland", "Italy", "Latvia", "Liechtenstein", "Lithuania", "Luxembourg", "Malta", "Netherlands", "Norway", "Poland", "Portugal", "Romania", "Slovakia", "Slovenia", "Spain", "Sweden", "Switzerland", "Turkey", "United Kingdom" ] }, "default": [ "all" ] }, "datePreset": { "title": "Period", "enum": [ "last7", "last30", "last90", "last180", "last365", "custom" ], "type": "string", "description": "Ads shown in this period. TikTok keeps an ad for one year after it was last shown. Choose \"Custom dates\" to use the two date fields below.", "default": "last30" }, "dateFrom": { "title": "From (custom period)", "type": "string", "description": "First day (YYYY-MM-DD). Used only when Period is \"Custom dates\"." }, "dateTo": { "title": "To (custom period)", "type": "string", "description": "Last day (YYYY-MM-DD). Used only when Period is \"Custom dates\"; empty = today." }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "TikTok's own website shows only active ads by default; this Actor returns active and inactive ads unless you choose otherwise.", "default": "all" }, "adFormat": { "title": "Ad format", "enum": [ "all", "video", "image", "text" ], "type": "string", "description": "Only ads of this format.", "default": "all" }, "sortBy": { "title": "Sort by", "enum": [ "newest", "oldest", "publishedNewest", "publishedOldest", "reachHigh", "reachLow" ], "type": "string", "description": "Order of the ads for advertiser searches, exact phrases and searches without a term (it also decides which ads you get when there are more than your maximum). Unquoted keyword searches come mostly in TikTok's relevance order. \"Reach\" = unique users who saw the ad.", "default": "newest" }, "maxAdsPerQuery": { "title": "Max ads per search term", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Stop after this many ads for each search term (at most 5,000).", "default": 100 }, "includeDetails": { "title": "Ad details (targeting, reach by country, who paid)", "type": "boolean", "description": "Open each ad's detail page: targeting (age, gender, countries, audience size, interests, custom audiences), unique users by country, age and gender, who paid, the advertiser's registered country and TikTok account, landing page, call to action and objective. Billed as an extra \"ad-details\" event per ad that has them. Turn off for a faster, cheaper list.", "default": true }, "output": { "title": "Output", "enum": [ "ads", "advertisers", "both" ], "type": "string", "description": "**Ads**: one row per ad. **Advertisers**: one row per advertiser (ads found, first/last shown, countries reached, summed reach, landing domains, who paid, TikTok account). **Both**: ad rows followed by advertiser rows.", "default": "ads" }, "topAdsCountries": { "title": "Countries", "type": "array", "description": "Top Ads are listed per country. One search per country.", "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" ] }, "default": [ "US" ] }, "topAdsPeriod": { "title": "Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Top Ads of the last 7, 30 or 180 days.", "default": "30" }, "topAdsSortBy": { "title": "Sort by", "enum": [ "for_you", "like", "ctr", "impression", "play_6s_rate", "play_2s_rate", "cvr" ], "type": "string", "description": "TikTok's ranking of the Top Ads.", "default": "for_you" }, "topAdsObjectives": { "title": "Campaign objectives", "type": "array", "description": "Only ads with these objectives. Empty = all.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "8", "15" ], "enumTitles": [ "Traffic", "App Installs", "Conversions", "Video Views", "Reach", "Lead Generation", "Product sales" ] }, "default": [] }, "topAdsIndustries": { "title": "Industries", "type": "array", "description": "Only ads from these industries. Empty = all.", "items": { "type": "string", "enum": [ "22000000000", "16000000000", "20000000000", "12000000000", "14000000000", "24000000000", "30000000000", "10000000000", "13000000000", "27000000000", "25000000000", "29000000000", "21000000000", "18000000000", "26000000000", "23000000000", "19000000000", "28000000000", "15000000000", "17000000000", "11000000000" ], "enumTitles": [ "Apparel & Accessories", "Appliances", "Apps", "Baby, Kids & Maternity", "Beauty & Personal Care", "Business Services", "E-Commerce (Non-app)", "Education", "Financial Services", "Food & Beverage", "Games", "Health", "Home Improvement", "Household Products", "Life Services", "News & Entertainment", "Pets", "Sports & Outdoor", "Tech & Electronics", "Travel", "Vehicle & Transportation" ] }, "default": [] }, "topAdsLanguages": { "title": "Ad languages", "type": "array", "description": "Only ads in these languages. Empty = all.", "items": { "type": "string", "enum": [ "en", "es", "ar", "vi", "th", "de", "id", "pt", "fr", "ms", "nl", "ja", "it", "ro", "zh-Hant", "ko" ], "enumTitles": [ "English", "Spanish", "Arabic", "Vietnamese", "Thai", "German", "Indonesian", "Portuguese", "French", "Malay", "Dutch", "Japanese", "Italian", "Romanian", "Chinese (Traditional)", "Korean" ] }, "default": [] }, "maxTopAds": { "title": "Max Top Ads per country", "minimum": 1, "maximum": 3000, "type": "integer", "description": "Stop after this many ads per country.", "default": 100 }, "sweepFilters": { "title": "Collect more than 20 ads per search", "type": "boolean", "description": "Without a TikTok login, Creative Center shows only 20 ads per filter combination. With this on, the Actor also asks for other sort orders, each objective and each industry, and merges the unique ads (no login, no cookies).", "default": true }, "includeTopAdDetails": { "title": "Ad details (landing page, comments, shares, countries)", "type": "boolean", "description": "Open each Top Ad's detail: landing page, comments, shares, all objectives and countries, source. Included in the \"top-ad\" event.", "default": true }, "includeTopAdAnalytics": { "title": "Analytics (retention and CTR curves)", "type": "boolean", "description": "Second-by-second retention curve (share of viewers still watching) and CTR curve for each ad. Billed as an extra \"top-ad-analytics\" event per ad that has them.", "default": false }, "onlyNewAds": { "title": "Only new ads", "type": "boolean", "description": "Deliver (and charge) only ads that earlier runs with the same monitor name did not deliver. The memory is kept per search term, countries and filters, in a key-value store in your account.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Use a different name for each separate watch list (letters, digits and dashes)." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed: the Actor starts with Apify's own IP and switches to Apify residential proxy by itself if TikTok limits it (Top Ads first try Apify datacenter proxy). A proxy you set here is always used for the Ad Library.", "default": { "useApifyProxy": false } }, "maxConcurrency": { "title": "Parallel requests", "minimum": 1, "maximum": 8, "type": "integer", "description": "How many ad details are fetched at the same time.", "default": 4 } } }, "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 } } } } } } } } } }