{ "openapi": "3.0.1", "info": { "title": "TikTok Ads", "description": "Scrape ads from the TikTok Ad Library by keyword, advertiser name, or URL. Export advertiser details, creatives, first/last shown dates, audience size, targeting data, and permanently download media files. No login required. ♾️ Unlimited results.", "version": "0.1", "x-build-id": "C3AkFdDzlL07bbEBs" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dz_omar~tiktok-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dz_omar-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/dz_omar~tiktok-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-dz_omar-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/dz_omar~tiktok-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-dz_omar-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": { "maxResults": { "title": "Maximum Results Per Input", "minimum": 0, "type": "integer", "description": "Maximum number of ads to collect per URL and per keyword filter. Set to 0 for UNLIMITED — collect every ad a search returns, with no 1,000-result cap.\n\nTotal results = (number of URLs + number of keywords) × Maximum Results.\n\nExample: 5 URLs + 6 keywords = 11 inputs. At 16 Maximum Results: 11 × 16 = 176 ads maximum. To pull tens of thousands of ads, set this to 0 and add more keywords, regions, or date ranges — each search runs independently.", "default": 10 }, "fetchAdDetail": { "title": "🔍 Fetch Ad Detail", "type": "boolean", "description": "Whether to fetch detailed information for each ad. If false, only summary information from the search results is collected. If true, the scraper makes an additional request per ad to collect the full advertiser profile, targeting parameters, and impression breakdowns which increases runtime and cost.", "default": false }, "downloadMedia": { "title": "⬇️ Download Media (video + images)", "type": "boolean", "description": "Download each ad's video and images to permanent storage and add the download links to the output.\n\n⚠️ This makes the run SIGNIFICANTLY SLOWER every ad triggers a separate download (roughly a few seconds per ad), so 1,000 ads can add a long wait. TikTok's own media links expire after a few hours; this option re-hosts them so they stay accessible.\n\nDownloads are handled by the Universal Downloader actor and saved to YOUR account's storage (free accounts: files expire in ~7 days; paid accounts: retained). Leave off if you only need the ad metadata and the original (short-lived) media URLs.", "default": false }, "startUrls": { "title": "Start URLs", "type": "array", "description": "One or more full library.tiktok.com/ads URLs. Copy the URL from your browser after applying all filters on the TikTok Ad Library site.", "items": { "type": "object", "properties": { "url": { "title": "TikTok Ad Library URL", "type": "string", "description": "Direct URL from the TikTok Ad Library. Must start with https://library.tiktok.com/ads", "pattern": "^https://library\\.tiktok\\.com/ads.*" } } } }, "keywords": { "title": "Keyword Filters", "type": "array", "description": "One or more keyword search configurations. Each entry requires a keyword and optionally a region, date range, and sort order.", "items": { "type": "object", "properties": { "query": { "title": "Keyword or Advertiser Name", "type": "string", "description": "The keyword or advertiser name to search for. LEAVE EMPTY to return every ad matching the country, dates and filters below — the same as searching TikTok's Ad Library with an empty search box. An empty search is capped at 5,000 ads per entry, so narrow it with the filters or add a keyword to go deeper.", "editor": "textfield", "maxLength": 40 }, "searchAsAdvertiser": { "title": "Search as advertiser", "type": "boolean", "description": "Off (default): treat the text as a keyword and match it against ad content. On: return every ad from ONE specific advertiser, which reaches far more of that advertiser's ads than a keyword search does. TikTok matches advertisers by their exact registered company name (\"NIKE Retail B.V.\", not \"nike\") — if what you type isn't an exact match, the scraper looks the name up automatically and uses the closest registered advertiser, reporting which one it picked in the log.", "default": false }, "region": { "title": "🌍 Region", "type": "string", "description": "Country to filter by. Selects one region per search the TikTok API processes one region at a time. Use 'All regions' to search across all EU/EEA regions in a single query.", "editor": "select", "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 regions (EU/EEA)", "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" ], "default": "all" }, "dateFrom": { "title": "Date From", "type": "string", "description": "Start date for the search range. Defaults to roughly one year ago if omitted (the TikTok Ad Library retains about one year of history).", "editor": "datepicker", "example": "2026-01-01" }, "dateTo": { "title": "Date To", "type": "string", "description": "End date for the search range. Defaults to today if omitted.", "editor": "datepicker", "example": "2026-06-03" }, "sortOrder": { "title": "Sort Order", "type": "string", "description": "How to sort results for this keyword search.", "editor": "select", "enum": [ "newest", "oldest", "created", "created-asc", "popular", "unpopular" ], "enumTitles": [ "Last shown date: Newest to oldest", "Last shown date: Oldest to newest", "Publication date: Newest to oldest", "Publication date: Oldest to newest", "Unique users seen: High to low", "Unique users seen: Low to high" ], "default": "newest" }, "adType": { "title": "🎬 Ad Type", "type": "string", "description": "Only return ads of this creative format. 'Text' is offered by TikTok but currently returns no results.", "editor": "select", "enum": [ "all", "video", "image", "text" ], "enumTitles": [ "All formats", "Video", "Image", "Text" ], "default": "all" }, "adStatus": { "title": "📶 Ad Status", "type": "string", "description": "Only return ads with this delivery status. 'Active' means still running.", "editor": "select", "enum": [ "all", "active", "inactive" ], "enumTitles": [ "All statuses", "Active", "Inactive" ], "default": "all" }, "gender": { "title": "⚧ Gender", "type": "string", "description": "Only return ads targeted at this gender.", "editor": "select", "enum": [ "all", "female", "male" ], "enumTitles": [ "All genders", "Female", "Male" ], "default": "all" }, "ages": { "title": "🎂 Age Groups", "type": "array", "description": "Only return ads targeted at these age bands. Leave empty for all ages.", "editor": "select", "items": { "type": "string", "enum": [ "13,17", "18,24", "25,34", "35,44", "45,54", "55,100" ], "enumTitles": [ "13 - 17", "18 - 24", "25 - 34", "35 - 44", "45 - 54", "55+" ] } }, "adReach": { "title": "📊 Unique Reach", "type": "array", "description": "Only return ads within these unique-reach bands. Leave empty for all reach levels.", "editor": "select", "items": { "type": "string", "enum": [ "0-10K", "10K-100K", "100K+" ], "enumTitles": [ "Under 10K", "10K - 100K", "Over 100K" ] } } }, "additionalProperties": false } }, "commercialContent": { "title": "Commercial Content Filters", "type": "array", "description": "One or more commercial-content searches. Each entry runs independently with its own creator, country, date range, and sort order.", "items": { "type": "object", "properties": { "creatorUsername": { "title": "Creator Username", "type": "string", "description": "The creator's EXACT TikTok username, e.g. 'abu.ali7691' (a leading @ is fine). This is not a keyword search — a brand or topic will return nothing. Leave empty to collect every creator in the selected country, which is capped at 5,000 records per entry because that search can reach tens of millions of results.", "editor": "textfield", "maxLength": 40 }, "region": { "title": "🌍 Creator Country", "type": "string", "description": "The country where the creator registered on TikTok — note this is the CREATOR's country, not where the video was shown. Use 'All countries' to search every EU/EEA region at once.", "editor": "select", "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 regions (EU/EEA)", "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" ], "default": "all" }, "dateFrom": { "title": "Date From", "type": "string", "description": "Earliest POSTED date to include. Defaults to roughly one year ago if omitted.", "editor": "datepicker", "example": "2026-01-01" }, "dateTo": { "title": "Date To", "type": "string", "description": "Latest POSTED date to include. Defaults to today if omitted.", "editor": "datepicker", "example": "2026-06-01" }, "sortOrder": { "title": "Sort Order", "type": "string", "description": "How to sort results for this commercial-content search.", "editor": "select", "enum": [ "newest", "oldest", "most-viewed", "least-viewed" ], "enumTitles": [ "Posted date: Newest to oldest", "Posted date: Oldest to newest", "Video views: High to low", "Video views: Low to high" ], "default": "newest" } } } } } }, "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 } } }, "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 } } } } } } } } } }