{ "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.2", "x-build-id": "KjC3Zt31bgha6eSNP" }, "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": { "mode": { "title": "🧭 Which surface to scrape", "enum": [ "creative_center", "eu_dsa_library" ], "type": "string", "description": "Creative Center = global best-performing ads leaderboard (the default; works worldwide). EU Ad Library = the DSA transparency library (EU-only, but exposes per-region age/gender/reach targeting). If you leave this blank, the actor infers the mode from which fields you fill." }, "ccCountries": { "title": "🌍 Countries (Creative Center)", "type": "array", "description": "One or more of the 81 supported countries. Each country is queried independently (TikTok serves a per-country Top-Ads leaderboard). Includes full MENA coverage (SA/AE/EG/QA/KW/BH/OM/JO/IQ/LB/MA/DZ). Default: United States.", "items": { "type": "string", "enum": [ "US", "GB", "SA", "AE", "EG", "DE", "FR", "ES", "IT", "NL", "BR", "MX", "AR", "CO", "CL", "PE", "CA", "AU", "NZ", "JP", "KR", "TW", "TH", "VN", "ID", "MY", "PH", "SG", "PK", "BD", "LK", "KH", "KZ", "AZ", "BY", "TR", "IL", "ZA", "NG", "KE", "MA", "DZ", "QA", "KW", "BH", "OM", "JO", "IQ", "LB", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "GR", "HU", "IE", "LV", "LT", "NO", "PL", "PT", "RO", "RS", "SK", "SI", "SE", "CH", "UY", "BO", "CR", "DO", "EC", "GT", "PA", "PY", "PR" ], "enumTitles": [ "United States", "United Kingdom", "Saudi Arabia", "United Arab Emirates", "Egypt", "Germany", "France", "Spain", "Italy", "Netherlands", "Brazil", "Mexico", "Argentina", "Colombia", "Chile", "Peru", "Canada", "Australia", "New Zealand", "Japan", "South Korea", "Taiwan", "Thailand", "Vietnam", "Indonesia", "Malaysia", "Philippines", "Singapore", "Pakistan", "Bangladesh", "Sri Lanka", "Cambodia", "Kazakhstan", "Azerbaijan", "Belarus", "Turkey", "Israel", "South Africa", "Nigeria", "Kenya", "Morocco", "Algeria", "Qatar", "Kuwait", "Bahrain", "Oman", "Jordan", "Iraq", "Lebanon", "Austria", "Belgium", "Bulgaria", "Croatia", "Cyprus", "Czechia", "Denmark", "Estonia", "Finland", "Greece", "Hungary", "Ireland", "Latvia", "Lithuania", "Norway", "Poland", "Portugal", "Romania", "Serbia", "Slovakia", "Slovenia", "Sweden", "Switzerland", "Uruguay", "Bolivia", "Costa Rica", "Dominican Republic", "Ecuador", "Guatemala", "Panama", "Paraguay", "Puerto Rico" ] } }, "ccPeriods": { "title": "📅 Time windows (Creative Center)", "type": "array", "description": "TikTok exposes exactly three look-back windows for top ads. Select one or more.", "items": { "type": "string", "enum": [ "7", "30", "180" ], "enumTitles": [ "Last 7 days", "Last 30 days", "Last 180 days" ] } }, "ccOrderBy": { "title": "📊 Sort / ranking (Creative Center)", "type": "array", "description": "Which leaderboard ranking(s) to pull. Each ranking surfaces a different top-20, so selecting several widens coverage.", "items": { "type": "string", "enum": [ "ctr", "like", "play_2s_rate", "for_you", "impression" ], "enumTitles": [ "Highest CTR", "Most liked", "Best 2-second hook rate", "For You (trending)", "Most impressions" ] } }, "ccIndustries": { "title": "🏭 Industries (Creative Center, optional)", "type": "array", "description": "Optional. Filter to one or more industries. Leave empty for all industries. Each selected industry multiplies the filter fan-out.", "items": { "type": "string", "enum": [ "10000000000", "11000000000", "12000000000", "13000000000", "14000000000", "15000000000", "16000000000", "17000000000", "18000000000", "19000000000", "20000000000", "21000000000", "22000000000", "23000000000", "24000000000", "25000000000", "26000000000", "27000000000", "28000000000", "29000000000", "30000000000" ], "enumTitles": [ "Education", "Vehicle & Transportation", "Baby, Kids & Maternity", "Financial Services", "Beauty & Personal Care", "Tech & Electronics", "Appliances", "Travel", "Household Products", "Pets", "Apps", "Home Improvement", "Apparel & Accessories", "News & Entertainment", "Business Services", "Games", "Life Services", "Food & Beverage", "Sports & Outdoor", "Health", "E-Commerce (Non-app)" ] } }, "ccObjectives": { "title": "🎯 Campaign objectives (Creative Center, optional)", "type": "array", "description": "Optional. Filter by the advertiser's campaign objective. Leave empty for all.", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "8", "15" ], "enumTitles": [ "Traffic", "App Installs", "Conversions", "Video Views", "Reach", "Lead Generation", "Product Sales" ] } }, "ccAdLanguages": { "title": "🗣️ Ad languages (Creative Center, optional)", "type": "array", "description": "Optional. Filter ads by creative language. Useful for MENA (Arabic) or LATAM (Spanish/Portuguese) creative research. Leave empty for 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" ] } }, "ccIncludeDetail": { "title": "🔎 Enrich each ad with detail (landing page, keywords, share/comment)", "type": "boolean", "description": "Fetch the per-ad detail endpoint to add the advertiser's LANDING PAGE URL, ad keywords, share/comment counts, campaign objectives, and source. Adds $1.50 per 1,000 ads. Disable to save cost if you only need the list-level leaderboard metrics (title/brand/CTR/likes/video).", "default": true }, "keywords": { "title": "🔍 Keywords (EU Ad Library)", "type": "array", "description": "EU Ad Library only. Search terms matched against ads in each selected EU region. Hard-capped at 1,000 results per query by TikTok — use Advertiser names for deeper drills. Leave blank if using the Creative Center mode.", "items": { "type": "string" } }, "advertiserNames": { "title": "🏷️ Advertiser names (EU Ad Library, auto-resolves to biz IDs)", "type": "array", "description": "EU Ad Library only. Advertiser names (e.g. Temu, Sephora, Shein) — auto-resolved to TikTok biz IDs, then deep-paginated UNCAPPED. Best mode for serious advertiser research.", "items": { "type": "string" } }, "advertiserIds": { "title": "🆔 Advertiser biz IDs (EU Ad Library, direct)", "type": "array", "description": "EU Ad Library only. Known TikTok advertiser biz IDs (e.g. 7479838683156283393 for Temu). Skips the autocomplete step. Uncapped pagination per advertiser.", "items": { "type": "string" } }, "regions": { "title": "🌍 EU regions (EU Ad Library only)", "type": "array", "description": "EU Ad Library only. 33 supported DSA regions (EU/EEA/UK/CH/TR). Each region is queried independently with its own 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 (EU Ad Library only)", "type": "object", "description": "EU Ad Library only. Filter by ad first-shown date. Defaults to 2024-01-01 → today. Format: { \"start\": \"YYYY-MM-DD\", \"end\": \"YYYY-MM-DD\" }. TikTok's DSA library only contains ads from ~mid-2023 onwards.", "default": { "start": "2024-01-01", "end": "" } }, "mediaType": { "title": "🎞️ Media type (EU Ad Library only)", "enum": [ "all", "video", "image" ], "type": "string", "description": "EU Ad Library only. Filter ads by creative format. (Creative Center ads are all video.)", "default": "all" }, "includeTargetingDetail": { "title": "🎯 Per-region targeting drill-down (EU Ad Library only)", "type": "boolean", "description": "EU Ad Library only. Fetch the per-ad detail endpoint for per-region × age × gender × reach buckets — the DSA killer feature. Adds $0.50 per 1,000 ads.", "default": true }, "maxItems": { "title": "🔢 Max ads per run", "minimum": 1, "maximum": 50000, "type": "integer", "description": "Hard cap on total ads emitted (both modes). Default 20 (small demo, FREE within the 10-event trial). For production increase to 500–10000+. Creative Center yields ~20 unique ads per filter combo, so widen the filters to hit a high cap.", "default": 20 }, "useProxy": { "title": "🛡️ Use residential proxy", "type": "boolean", "description": "Route requests through Apify Residential Proxy for IP-rotation safety. Both surfaces work cookie-free without a proxy; enable for very large fan-outs or concurrent runs. Adds a 'proxy-fetch' charge ($0.002) per request.", "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 }, "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 } } } } } } } } } }