{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Library Scraper (EU): Ads, Targeting, Reach", "description": "Scrape the official TikTok Ad Library (EU/UK) without login: search by keyword or advertiser and get each ad's video, caption, dates, unique users seen, targeting (age, gender, interests, audience size) and reach by country. Monitor new ads.", "version": "1.1", "x-build-id": "ohtAVWDjAIbhHkZwU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hydrocore~tiktok-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hydrocore-tiktok-ad-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/hydrocore~tiktok-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-hydrocore-tiktok-ad-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/hydrocore~tiktok-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-hydrocore-tiktok-ad-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": "Words to search in TikTok's ad library, one per line, for example a brand (adidas), a product (running shoes) or an advertiser name. TikTok matches the advertiser name and the ad text. Leave empty if you only use advertisers, links or ad ids.", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers (exact company)", "type": "array", "description": "Get only the ads of one company, one per line, for example \"NIKE Retail B.V.\". The Actor picks the matching advertiser from TikTok's own suggestions (exact name first, otherwise the closest one; the run log shows which one was used).", "items": { "type": "string" } }, "startUrls": { "title": "Ad library links (optional)", "type": "array", "description": "Paste links copied from library.tiktok.com: a search page (with your filters already set) or a single ad page (library.tiktok.com/ads/detail/?ad_id=...).", "items": { "type": "string" } }, "adIds": { "title": "Ad ids (optional)", "type": "array", "description": "TikTok ad ids (the number after ad_id= in an ad link) to fetch full details for.", "items": { "type": "string" } }, "country": { "title": "Country where the ad was shown", "enum": [ "all", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE", "CH", "TR", "GB" ], "type": "string", "description": "TikTok's ad library only covers ads shown in the EU, EEA, Switzerland, the UK and Turkey. Pick one country or all of them.", "default": "all" }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads last shown on or after this date. Leave empty for the last 12 months. You can also write a relative date like \"30 days\"." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date. Leave empty for today." }, "sortBy": { "title": "Sort ads by", "enum": [ "lastShownNewest", "lastShownOldest", "firstShownNewest", "firstShownOldest", "mostUsersSeen", "fewestUsersSeen" ], "type": "string", "description": "TikTok's own sort, applied before the limits below (so the top 20 by reach really are the 20 with most reach). Search links you paste keep their own sort.", "default": "lastShownNewest" }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 1, "maximum": 5000, "type": "integer", "description": "How many ads to save for each search term, advertiser or link. Newest (most recently shown) ads come first.", "default": 30 }, "maxAdsTotal": { "title": "Max ads in total", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Stop the whole run after this many ads. Leave empty or 0 for no limit." }, "includeDetails": { "title": "Include targeting and reach details", "type": "boolean", "description": "On (recommended): opens each ad's page to add the advertiser id and country, who paid, the campaign goal, targeting (age, gender, country, audience size, interests) and reach per country. Off: faster, but only the search-card fields (video, caption, dates, unique users seen). The price per ad is the same.", "default": true }, "includeAgeGenderBreakdown": { "title": "Add reach by age and gender", "type": "boolean", "description": "Adds impressions per age group and gender inside each country (only when details are on). Makes rows bigger.", "default": false }, "onlyNewAds": { "title": "Only new ads since the last run (monitoring)", "type": "boolean", "description": "Turn on for scheduled runs: saves (and charges) only ads this search has not returned before. The first run saves the current ads as the starting point.", "default": false }, "monitorKey": { "title": "Monitor name (optional)", "type": "string", "description": "Optional name for the memory of seen ads, for example \"competitors\". Use the same name to share it between tasks; leave empty and the Actor makes one from your searches." }, "maxSpendUsd": { "title": "Max spend (USD)", "type": "string", "description": "Optional hard limit for this run in US dollars, for example 1.50. The run stops before going over it. Apify's own \"Maximum cost per run\" also works." }, "proxyConfiguration": { "title": "Proxy (optional)", "type": "object", "description": "Not needed: the ad library is public. Turn on only if you see repeated \"did not answer\" errors.", "default": { "useApifyProxy": 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 } } } } } } } } } }