{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper: EU Ads, Targeting and Reach", "description": "Scrape TikTok's EU Ad Library (DSA) by keyword, advertiser name or id: advertiser, paid for by, first and last shown, unique users by country with age and gender split, targeting, ad text, landing page, video and image links. No login.", "version": "0.1", "x-build-id": "3X5ma07ufdi9MSQDj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/themineworks~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-themineworks-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/themineworks~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-themineworks-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/themineworks~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-themineworks-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 (keywords or advertiser names)", "type": "array", "description": "One search per line, matched the way the Ad Library's own search box matches: advertiser names and words in the ad text (nike, adidas, running shoes). Put a phrase in double quotes for an exact phrase match (\"just do it\"). Up to 100 searches per run; repeats are run once.", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers (exact names)", "type": "array", "description": "Optional. Every ad of one advertiser, one per line: the advertiser name exactly as the library shows it (adidas AG, NIKE Retail B.V., Zalando SE; capital letters do not matter). The actor finds the advertiser with the library's own advertiser lookup; a name that matches several advertiser accounts runs one search for each. To pin one account, write \"name | id\" with the advertiser_name and advertiser_id of a row, for example adidas AG | 6885261436319171329. A name the library does not know is reported in the run summary with its closest matches and costs nothing.", "items": { "type": "string" } }, "browseWithoutSearch": { "title": "Browse all ads (no search term)", "type": "boolean", "description": "Only used when there are no search terms and no advertisers: lists every ad shown in the chosen countries and dates, in the order set by Sort by.", "default": false }, "countries": { "title": "Countries", "type": "array", "description": "Ads shown in these countries. The library covers the EU and EEA, Switzerland, the United Kingdom and Turkey. Leave empty or pick All for every covered country.", "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 covered countries", "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" ] } }, "dateFrom": { "title": "Shown from (YYYY-MM-DD)", "type": "string", "description": "Optional. Ads shown on or after this day. Empty means 365 days before the end date." }, "dateTo": { "title": "Shown until (YYYY-MM-DD)", "type": "string", "description": "Optional. Ads shown on or before this day. Empty means today." }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 20, "maximum": 5000, "type": "integer", "description": "How many ads to collect for each search line, 20 to 5,000. The library lists at most 5,000 ads for one search; a search with fewer matches returns what it has.", "default": 20 }, "includeDetails": { "title": "Include details and targeting", "type": "boolean", "description": "Open each ad's detail record: advertiser id and country, paid for by, objective, landing page, call to action, unique users by country with the age and gender split, and the targeting (countries, ages, genders, interests, audience size and more). Untick for the list fields only (faster). With details on, an ad whose details TikTok will not serve is skipped and not charged.", "default": true }, "onlyNewAds": { "title": "Only new ads (for schedules)", "type": "boolean", "description": "Skip ads an earlier run of this actor already delivered to you, so a daily or weekly schedule returns and charges only ads it has not sent before.", "default": false }, "sortBy": { "title": "Sort by", "enum": [ "last_shown_newest", "last_shown_oldest", "first_shown_newest", "first_shown_oldest", "most_users", "fewest_users" ], "type": "string", "description": "Order of the results when browsing without a search term. With a search term TikTok ranks the ads by how well they match, as the library page does.", "default": "last_shown_newest" }, "adStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Active ads, inactive ads, or both.", "default": "all" }, "mediaType": { "title": "Ad type", "enum": [ "all", "video", "image" ], "type": "string", "description": "Video ads, image ads, or both.", "default": "all" }, "targetGender": { "title": "Targeted gender", "enum": [ "all", "female", "male" ], "type": "string", "description": "Only ads whose targeting includes this gender.", "default": "all" }, "targetAges": { "title": "Targeted age groups", "type": "array", "description": "Optional. Only ads targeting at least one of these age groups. Empty means all ages.", "items": { "type": "string", "enum": [ "13-17", "18-24", "25-34", "35-44", "45-54", "55+" ] } }, "uniqueUsers": { "title": "Unique users reached", "type": "array", "description": "Optional. Only ads in these reach bands. Empty means any reach.", "items": { "type": "string", "enum": [ "under_10k", "10k_100k", "over_100k" ], "enumTitles": [ "Under 10K", "10K to 100K", "Over 100K" ] } } } }, "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 } } } } } } } } } }