{ "openapi": "3.0.1", "info": { "title": "TikTok Ads EU — Library Scraper with Demographics", "description": "Scrape TikTok's EU Ad Library (library.tiktok.com) at scale. Get ads by keyword, advertiser name, or biz ID across 33 DSA regions. Per-region targeting drill-down. Uncapped advertiser deep-drill. Pay per ad scraped, no subs. $0.80 per 1,000 ads — 68% cheaper than competitors.", "version": "0.1", "x-build-id": "4K7ZaPieva5DR3cro" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/constructive_calm~tiktok-ad-library-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-constructive_calm-tiktok-ad-library-pro", "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/constructive_calm~tiktok-ad-library-pro/runs": { "post": { "operationId": "runs-sync-constructive_calm-tiktok-ad-library-pro", "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/constructive_calm~tiktok-ad-library-pro/run-sync": { "post": { "operationId": "run-sync-constructive_calm-tiktok-ad-library-pro", "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": { "keywords": { "title": "🔍 Keywords (search mode)", "type": "array", "description": "Type one or more search terms. We'll search TikTok's Ad Library for ads matching each keyword in each selected region. NOTE: keyword search is hard-capped at 1,000 results per query by TikTok. For deeper drills, use Advertiser names below. Leave blank if using Advertiser names or IDs.", "items": { "type": "string" } }, "advertiserNames": { "title": "🏷️ Advertiser names (auto-resolves to biz IDs)", "type": "array", "description": "Type one or more advertiser names (e.g. Temu, Sephora, Shein). We'll auto-resolve each to its TikTok advertiser biz ID via the autocomplete API, then deep-paginate UNCAPPED. Best mode for serious advertiser research — keyword cap of 1,000 doesn't apply.", "items": { "type": "string" } }, "advertiserIds": { "title": "🆔 Advertiser biz IDs (direct, skip resolution)", "type": "array", "description": "If you already know the TikTok advertiser biz IDs (e.g. 7479838683156283393 for Temu), paste them here. Skips the autocomplete step. Uncapped pagination per advertiser.", "items": { "type": "string" } }, "regions": { "title": "🌍 Regions (EU/EEA/UK/CH/TR only)", "type": "array", "description": "33 supported DSA regions. TikTok's Ad Library is EU-only (no US/JP/BR/IN). Each region is queried independently — ads may appear in multiple regions with different per-region targeting.", "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", "Czech Republic", "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" ] }, "default": [ "DE" ] }, "dateRange": { "title": "📅 Date range", "type": "object", "description": "Filter by ad first-shown date. Defaults to 2024-01-01 → today. Format: { \"start\": \"YYYY-MM-DD\", \"end\": \"YYYY-MM-DD\" }. NOTE: TikTok's DSA library only contains ads from ~mid-2023 onwards. Dates before that return HTTP 400 (gracefully skipped, no ads returned).", "default": { "start": "2024-01-01", "end": "" } }, "mediaType": { "title": "🎞️ Media type", "enum": [ "all", "video", "image" ], "type": "string", "description": "Filter ads by creative format. 'all' returns everything; 'video' / 'image' filter on the response.", "default": "all" }, "includeTargetingDetail": { "title": "🎯 Include per-region targeting drill-down (recommended)", "type": "boolean", "description": "Fetch the per-ad detail endpoint to get per-region × age × gender × reach buckets. This is the killer feature vs competitors. Adds $0.0005 per ad ($0.50 per 1,000). Disable to save cost if you only need list-level data.", "default": true }, "maxItems": { "title": "🔢 Max items per run", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Hard cap on total ads emitted across all keywords/advertisers. Default 20 (small demo, ~$0.016 with detail on, FREE within trial). For production scrapes increase to 500-10000+.", "default": 20 }, "useProxy": { "title": "🛡️ Use residential proxy (recommended for production)", "type": "boolean", "description": "Enable Apify Residential Proxy to bypass TikTok's IP-based rate limit. TikTok soft-rate-limits with 'limit exceed' when one IP makes too many requests (triggered by deep drills 500+ ads, OR concurrent runs from same actor). When rate-limited the actor gracefully skips and returns 0 ads with a warning. Adds 'proxy-fetch' charge per request ($0.002). Recommended ON for: deep paginate >500 ads, concurrent runs, all-33-regions scrapes. OFF for small one-shot queries (saves cost).", "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 } } } } } } } } } }