{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper – Targeting & Impressions", "description": "Scrape TikTok ads from the official TikTok Ad Library by advertiser or keyword. Get ad text, videos, dates, reach, landing pages, CTA, targeting (age, gender, interests) and impressions by country. EU, UK, CH, TR.", "version": "0.1", "x-build-id": "3u6j6R4TBzxUaAPL2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/expensive_marquess~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-expensive_marquess-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/expensive_marquess~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-expensive_marquess-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/expensive_marquess~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-expensive_marquess-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", "required": [ "queries" ], "properties": { "queries": { "title": "Advertisers, keywords or URLs", "type": "array", "description": "Any mix of: advertiser names (Nike), TikTok advertiser IDs (6876453864464188162), Ad Library search URLs, or ad detail URLs (library.tiktok.com/ads/detail/?ad_id=...).", "items": { "type": "string" } }, "searchType": { "title": "Treat plain text as", "enum": [ "advertiser", "keyword" ], "type": "string", "description": "How to interpret plain text entries. Advertiser IDs and URLs are detected automatically.", "default": "advertiser" }, "regions": { "title": "Countries", "type": "array", "description": "Countries where the ad was shown. TikTok publishes ads shown in the EU/EEA, Switzerland, the UK and Turkey.", "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 countries", "Austria (AT)", "Belgium (BE)", "Bulgaria (BG)", "Switzerland (CH)", "Cyprus (CY)", "Czech Republic (CZ)", "Germany (DE)", "Denmark (DK)", "Estonia (EE)", "Spain (ES)", "Finland (FI)", "France (FR)", "United Kingdom (GB)", "Greece (GR)", "Croatia (HR)", "Hungary (HU)", "Ireland (IE)", "Iceland (IS)", "Italy (IT)", "Liechtenstein (LI)", "Lithuania (LT)", "Luxembourg (LU)", "Latvia (LV)", "Malta (MT)", "Netherlands (NL)", "Norway (NO)", "Poland (PL)", "Portugal (PT)", "Romania (RO)", "Sweden (SE)", "Slovenia (SI)", "Slovakia (SK)", "Turkey (TR)" ] }, "default": [ "ALL" ] }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Default: 1 year ago." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Default: today." }, "sortBy": { "title": "Sort by", "enum": [ "last_shown_date,desc", "impression,desc", "create_time,desc", "create_time,asc" ], "type": "string", "description": "Order of results. Use 'Unique users reached' to find the biggest ads first.", "default": "last_shown_date,desc" }, "maxAdsPerQuery": { "title": "Max ads per query", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Stop after this many ads per query. 0 = as many as possible (TikTok returns up to 5,000 per search).", "default": 100 }, "includeDetails": { "title": "Include targeting, landing page and impressions", "type": "boolean", "description": "Adds landing page URL, call to action, objective, industry, who paid, targeting (age, gender, interests, languages, locations, audiences) and impressions by country, age and gender. One extra request per ad, so runs are slower.", "default": false }, "advertisersPerName": { "title": "Advertiser accounts per name", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many matching advertiser accounts to scrape for each name (an exact name match is always preferred).", "default": 1 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Use a residential proxy if runs are throttled.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }