{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper – EU/UK Ads, Targeting & Reach", "description": "Scrape the official TikTok Ads Library (EU/EEA, UK, CH, TR): ad text, video/image URLs, advertiser, first/last shown, reach, impressions by country/age/gender, targeting. Search by keyword or advertiser. Optional Creative Center top ads.", "version": "0.1", "x-build-id": "KAi0cnb0AY0XtdnlI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ferncrawl~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ferncrawl-tiktok-ads-library-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/ferncrawl~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-ferncrawl-tiktok-ads-library-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/ferncrawl~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-ferncrawl-tiktok-ads-library-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": { "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords searched in ad text and advertiser names (like the search box on library.tiktok.com). Each term is a separate search; maxAds applies per term. If nothing at all is entered (no terms, advertisers or IDs), 'nike' is used as a demo search.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Advertiser (legal entity) names, e.g. 'Adidas AG'. Resolved with TikTok's advertiser search; an exact (case-insensitive) match is used if available, otherwise up to 3 advertisers containing the name. Matches are listed in the OUTPUT summary.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "TikTok business IDs (the 'advertiserId' field of earlier results). Most precise way to track an advertiser.", "items": { "type": "string" } }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "Wrap search terms in quotes so the Library matches the exact phrase.", "default": false }, "regions": { "title": "Regions", "type": "array", "description": "Countries where the ad was shown. The TikTok Ads Library only covers the EU/EEA, United Kingdom, Switzerland and Türkiye. 'all' = all of them in one search.", "items": { "type": "string", "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" ], "enumTitles": [ "All supported regions", "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", "Türkiye" ] }, "default": [ "all" ] }, "lastNDays": { "title": "Last N days", "minimum": 1, "maximum": 366, "type": "integer", "description": "Ads shown in the last N days (ignored when 'Date from' is set). Note: the Library typically lags ~2 days.", "default": 30 }, "dateFrom": { "title": "Date from", "type": "string", "description": "Optional start date (YYYY-MM-DD)." }, "dateTo": { "title": "Date to", "type": "string", "description": "Optional end date (YYYY-MM-DD), default today." }, "maxAds": { "title": "Max ads per search", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum ads per search term / advertiser. You pay per ad returned.", "default": 20 }, "fetchDetails": { "title": "Fetch ad details", "type": "boolean", "description": "Adds landing page, CTA, objective, TikTok account, impressions by country/age/gender and targeting (age, gender, location, interests, audience size). Roughly 3x slower; turn off for a quick list.", "default": true }, "daySlicing": { "title": "Deep search (day slicing)", "type": "boolean", "description": "TikTok only lets you page ~100 results deep per search. When more ads are wanted, the actor also searches day by day to reach older/less popular ads.", "default": true }, "advertiserMatch": { "title": "Advertiser name matching", "enum": [ "exact", "contains" ], "type": "string", "description": "How advertiser names are resolved.", "default": "exact" }, "includeCreativeCenter": { "title": "Add Creative Center top ads", "type": "boolean", "description": "Also collect TikTok Creative Center 'Top Ads' (best-performing ads with CTR, likes, video) for the countries below. Works worldwide (not only EU). Starts a headless browser once — use 1024 MB memory. Charged as a separate event.", "default": false }, "ccCountries": { "title": "Creative Center countries", "type": "array", "description": "Two-letter country codes, e.g. US, GB, DE, JP.", "default": [ "US" ], "items": { "type": "string" } }, "ccPeriodDays": { "title": "Creative Center period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Ranking period.", "default": "30" }, "ccMaxAds": { "title": "Max Creative Center ads", "minimum": 1, "maximum": 320, "type": "integer", "description": "Total cap. Without login TikTok shows ~20 ads per country and sort order (4 sort orders are combined).", "default": 20 }, "ccFetchDetails": { "title": "Creative Center details", "type": "boolean", "description": "Adds landing page, comments, shares and countries.", "default": true }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. Works without a proxy; Apify datacenter proxy also works. Residential proxy is not needed.", "default": { "useApifyProxy": false } }, "minRequestIntervalSecs": { "title": "Min seconds between requests", "minimum": 0.3, "maximum": 10, "type": "number", "description": "Politeness delay between requests to TikTok.", "default": 1 } } }, "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 } } } } } } } } } }