{ "openapi": "3.0.1", "info": { "title": "TikTok Ad Library - Free To Use", "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": "1f1glakp3t8dSfgi8" }, "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.", "editor": "textfield", "minLength": 1, "maxLength": 40 }, "searchAsAdvertiser": { "title": "Search as advertiser", "type": "boolean", "description": "Off (default): treat the text as a keyword and match it against ad content (TikTok's \"Search this exact phrase\"). On: treat the text as an advertiser name and return that advertiser's ads (TikTok's \"Advertiser name\").", "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": [ "Newest first (last shown date ↓)", "Oldest first (last shown date ↑)", "Recently created first", "Oldest created first", "Most popular first (unique viewers ↓)", "Least popular first (unique viewers ↑)" ], "default": "newest" } }, "required": [ "query" ], "additionalProperties": 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 } } }, "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 } } } } } } } } } }