{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library API | EU Ads, Ad Targeting, $1.40/1K", "description": "Scrape the TikTok Ads Library at an all-in $1.40 per 1,000 ads with no platform usage added, several queries per run, an only-new-ads mode and a Slack digest. EU/EEA, UK, CH and TR ads with targeting and reach by country, age and gender on every ad. No login.", "version": "0.2", "x-build-id": "uJeLfTnIrkwXzQ7G7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/aurelix~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-aurelix-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/aurelix~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-aurelix-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/aurelix~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-aurelix-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": { "queries": { "title": "Keywords, advertiser names or Ad Library URLs", "type": "array", "description": "Each entry is one of: a keyword or advertiser name (e.g. 'sneakers', 'Nike'); a TikTok Ad Library search URL copied from the browser (e.g. 'https://library.tiktok.com/ads?region=DE&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=6876453864464188162&query_type=2'), whose own country, dates and advertiser override the fields below; or one ad's id or detail-page URL (e.g. 'https://library.tiktok.com/ads/detail/?ad_id=1878794271206849'). Pick an advertiser from the site's suggestions and copy the URL to get exactly that advertiser's ads.", "default": [], "items": { "type": "string" } }, "country": { "title": "Ad target country", "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", "all" ], "type": "string", "description": "Country the ads were shown in. The TikTok Ad Library covers the EU/EEA, Switzerland, the UK and Turkey; pick 'All covered countries' to search them all at once. Run several single countries by adding Ad Library URLs with their own country to 'queries'.", "default": "FR" }, "days": { "title": "Last shown in the past N days", "minimum": 1, "maximum": 365, "type": "integer", "description": "Keep ads last shown within this many days before the run, e.g. 30. Maximum 365 (TikTok keeps ads for a year after they last ran).", "default": 30 }, "sortBy": { "title": "Sort by", "enum": [ "last_shown", "published" ], "type": "string", "description": "'last_shown' = most recently shown first; 'published' = newest ads first.", "default": "last_shown" }, "maxResultsPerQuery": { "title": "Max ads per query", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Exact upper limit of ads returned for each query, e.g. 100. The run never returns more, and stops early when the results run out. TikTok's search shows at most about 5,000 ads per query.", "default": 100 }, "includeDetails": { "title": "Include targeting summary", "type": "boolean", "description": "Open each ad's public detail page to add the targeting summary (countries, ages, genders, interests, audience size, reach by country, age and gender), objective, call to action, landing page, paid-for-by and the advertiser's registered location. Turn off for a faster list with dates, reach, text and media only. Same price either way.", "default": true }, "incremental": { "title": "Only new ads since last run", "type": "boolean", "description": "Return only ads not returned by a previous run with the same queries. Use with a schedule to track new competitor ads.", "default": false }, "stateKey": { "title": "Incremental state name (optional)", "type": "string", "description": "Name for the 'new since last run' memory. Leave empty to derive it from the queries; set it to keep separate feeds apart." }, "slackWebhookUrl": { "title": "Slack webhook URL (optional)", "type": "string", "description": "After each run, post a short digest to Slack: how many results were saved (new ones only when 'Only new ads since last run' is on) and the top 10 with links, e.g. https://hooks.slack.com/services/T000/B000/XXXX. Nothing is posted when the run saved nothing. Leave empty to skip." }, "webhookUrl": { "title": "Webhook URL (optional)", "type": "string", "description": "After each run, POST the same digest as JSON (actor, newOnly, count, items = top 10 results, runUrl, text) to any URL, e.g. a Zapier, Make or n8n webhook. Nothing is sent when the run saved nothing. Leave empty to skip." } } }, "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 } } } } } } } } } }