{ "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, creative type, first/last shown dates, audience size, video/image creatives, and download media files permanently. Full targeting data (regions, age, gender) on demand. No login required.", "version": "0.0", "x-build-id": "9i6C0urIbFm96EuY1" }, "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 to collect everything the API returns (up to the TikTok hard cap of 1,000 per query).\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.", "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.*" } } }, "default": [ { "url": "https://library.tiktok.com/ads?region=DE&adv_name=nike&sort_type=last_shown_date,desc" } ] }, "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 2016-01-01 if omitted.", "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 } } } } } } } } } }