{ "openapi": "3.0.1", "info": { "title": "Tiktok Ads Scraper", "description": "Tiktok Ads Scraper collects ads from TikTok's public Commercial Content Library: creative video or image, ad text, advertiser, landing page, objective and targeting by country, age and gender. No login needed. Export as JSON, CSV or Excel, or use the API.", "version": "0.4", "x-build-id": "DLXYplarqRNMteDF6" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/socialdataapi~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-socialdataapi-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/socialdataapi~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-socialdataapi-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/socialdataapi~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-socialdataapi-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", "required": [ "startUrls" ], "properties": { "startUrls": { "title": "šŸ”Ž Search terms, advertiser names, or Ad Library URLs", "type": "array", "description": "One entry per search. Each entry can be:\nā€¢ a keyword (e.g. `gaming`, `skincare`)\nā€¢ an advertiser / brand name (e.g. `NVIDIA GmbH`) ā€” set Search type to `advertiser`\nā€¢ a full TikTok Ad Library URL (e.g. `https://library.tiktok.com/ads?region=all&adv_name=NVIDIA&query_type=1&...`) ā€” region, date range, sort and query type are then read from the URL itself.", "items": { "type": "string" } }, "searchType": { "title": "šŸ”Ž Search type", "enum": [ "keyword", "advertiser" ], "type": "string", "description": "`keyword` performs a fuzzy full-text search over ad text and advertiser names. `advertiser` matches the advertiser/brand name (TikTok query_type=2). Ignored for entries that are full Ad Library URLs.", "default": "keyword" }, "region": { "title": "šŸ“ Region", "enum": [ "all", "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" ], "type": "string", "description": "Country whose ad delivery you want. `all` covers every supported country. The TikTok Commercial Content Library only publishes EU/EEA + UK, Switzerland and Turkey ads ā€” US and other markets are not available.", "default": "all" }, "sortOrder": { "title": "šŸ”ƒ Sort order", "enum": [ "last_shown_date,desc", "last_shown_date,asc" ], "type": "string", "description": "Order in which TikTok returns the ads. Only these two orders are accepted by TikTok's API.", "default": "last_shown_date,desc" }, "daysBack": { "title": "šŸ“… Look back (days)", "minimum": 1, "maximum": 1095, "type": "integer", "description": "Search ads shown within the last N days. Ignored when both `dateFrom` and `dateTo` are set.", "default": 90 }, "dateFrom": { "title": "šŸ“… Date from (optional)", "type": "string", "description": "Start of the date range, e.g. `2025-01-01`. Overrides `Look back (days)`." }, "dateTo": { "title": "šŸ“… Date to (optional)", "type": "string", "description": "End of the date range, e.g. `2026-01-01`. Defaults to today." }, "maxAds": { "title": "šŸ”¢ Max ads per search term", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap of ads scraped for each entry above. TikTok returns at most ~84 ads per single query+time-window, so for higher values the date range is automatically split into 30-day and then 7-day windows to collect more unique ads. Free plan: up to 20 ads per run (all search terms together) and 200 per month; paid plans have no limit.", "default": 20 }, "maxItems": { "title": "šŸ”¢ Max ads in total (optional)", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Global hard cap across all search terms. Leave empty for no global limit. Free plan: up to 20 ads per run (all search terms together) and 200 per month, regardless of this value; paid plans have no limit." }, "includeAdDetails": { "title": "āœ… Fetch full ad details", "type": "boolean", "description": "Fetch the per-ad detail payload (advertiser identity, paid-by sponsor, landing page URL, CTA, objective, targeting breakdown, linked TikTok account, per-country impressions). Turn off for a much faster, lighter run that only returns the listing fields.", "default": true }, "detailConcurrency": { "title": "āš” Detail fetch concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many ad detail requests to run in parallel (1-20). This platform's detail endpoint is fragile under heavy load; lower this if you see many retries/blocks in the log.", "default": 12 }, "proxyConfiguration": { "title": "šŸŒ Proxy configuration", "type": "object", "description": "Recommended: keep Apify Proxy ON. This platform rate-limits requests per IP, so the actor rotates a proxy session whenever it gets blocked. Without a proxy you still get results from the actor's own connection, but you are more likely to hit temporary blocks on higher volumes.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }