{
"openapi": "3.0.1",
"info": {
"title": "TikTok Ads Library Scraper — EU TikTok Ad Library Search",
"description": "Scrape the TikTok Ads Library by keyword, advertiser, or ad ID across 30+ EU/EEA countries. Quick mode returns ad creatives and dates at $0.005 per ad; full mode adds video URLs, targeting demographics, and reach. Search up to 10 keywords in a single run.",
"version": "0.7",
"x-build-id": "BNgaRa1JkqBMOzHE7"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/jy-labs~tiktok-ad-library-fast-search/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-jy-labs-tiktok-ad-library-fast-search",
"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/jy-labs~tiktok-ad-library-fast-search/runs": {
"post": {
"operationId": "runs-sync-jy-labs-tiktok-ad-library-fast-search",
"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/jy-labs~tiktok-ad-library-fast-search/run-sync": {
"post": {
"operationId": "run-sync-jy-labs-tiktok-ad-library-fast-search",
"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": {
"adIds": {
"title": "Ad IDs",
"type": "array",
"description": "Enter specific TikTok ad IDs to scrape directly. The scraper will skip the search and fetch detail pages for these ads. Find ad IDs from TikTok Ad Library URLs (e.g., library.tiktok.com/ads/detail/?ad_id=1858053691202865).",
"items": {
"type": "string"
}
},
"query": {
"title": "Search Query",
"type": "string",
"description": "Enter a company name, brand, domain, or keyword to search for in the TikTok Ad Library. For example: Nike, shopify.com, or fitness app."
},
"advertiserName": {
"title": "Advertiser Name",
"type": "string",
"description": "Enter an advertiser's business name. When both Search Query and Advertiser Name are provided, this field takes priority."
},
"keywords": {
"title": "Additional Keywords",
"type": "array",
"description": "Add more keywords to search in the same run (max 10 total). Each keyword is searched separately and all results are combined. Great for comparing competitors or tracking multiple brands.",
"items": {
"type": "string"
}
},
"country": {
"title": "Country",
"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": "Filter ads by the country they target. Select a specific country or use 'All Countries' to search across all available regions. Tip: If you leave the search query empty, select a specific country instead of 'All'.",
"default": "ALL"
},
"startDate": {
"title": "Start Date",
"type": "string",
"description": "Show only ads published on or after this date (YYYY-MM-DD). Leave empty for all dates (no default)."
},
"endDate": {
"title": "End Date",
"type": "string",
"description": "Show only ads published on or before this date (YYYY-MM-DD). Leave empty for no upper date limit. Future dates are automatically capped to the current date."
},
"timezone": {
"title": "Timezone",
"type": "string",
"description": "Timezone for date interpretation (e.g., Europe/London, America/New_York). Leave empty for UTC."
},
"quickSearch": {
"title": "Quick Search Mode",
"type": "boolean",
"description": "Enable for 3-5x faster results by skipping detail page visits. Trade-off: targeting data, advertiser ID, video URLs, and impression data will be null. Recommended for large-volume searches where you only need basic ad information. With Quick Search off, each ad needs its own detail page (about 4–5.5 seconds), so results per keyword are limited by the per-keyword timeout (about 25 ads at the default 180 s). Ads whose detail page fails are delivered with detailStatus: \"failed\" and charged at the Quick Search price.",
"default": true
},
"phraseFilter": {
"title": "Full-Phrase Filter (multi-word searches)",
"type": "boolean",
"description": "For searches with two or more words, return and charge only ads whose caption, advertiser name, or landing page URL contains the whole phrase (case-insensitive). TikTok's own search is loose: Liquid Death also returns \"Liquid Love\" ads. Single-word searches are never filtered. Quick Search matches caption and advertiser name; Full Search also checks the landing URL. Turn off to get TikTok's raw results.",
"default": true
},
"orderBy": {
"title": "Sort Order",
"enum": [
"last_shown_date_newest_to_oldest",
"last_shown_date_oldest_to_newest",
"published_date_newest_to_oldest",
"published_date_oldest_to_newest",
"unique_users_seen_high_to_low",
"unique_users_seen_low_to_high"
],
"type": "string",
"description": "Choose how search results are sorted. Use 'Audience (Highest First)' to find the most-viewed ads.",
"default": "last_shown_date_newest_to_oldest"
},
"maxPages": {
"title": "Max Pages",
"minimum": 1,
"maximum": 300,
"type": "integer",
"description": "Maximum number of result pages to scrape. Each page contains up to 12 ads. TikTok limits the Ad Library to 300 pages (3,600 ads max per keyword).",
"default": 5
},
"maxResults": {
"title": "Max Results Per Keyword",
"minimum": 1,
"maximum": 3600,
"type": "integer",
"description": "Limit the number of ads extracted per keyword. Useful for controlling costs. If set lower than maxPages x 12, this value takes priority.",
"default": 60
},
"proxy": {
"title": "Proxy Configuration",
"type": "object",
"description": "Residential proxy is strongly recommended. TikTok actively blocks datacenter IP addresses. The default Apify RESIDENTIAL proxy provides the best reliability.",
"default": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
},
"requestHandlerTimeoutSecs": {
"title": "Timeout Per Keyword (seconds)",
"minimum": 60,
"maximum": 600,
"type": "integer",
"description": "Maximum time in seconds to spend on each keyword search. If timeout is reached, any ads already loaded will be saved (partial recovery). Partially recovered ads have no detail page data and are charged at the Quick Search price. Full Search opens one detail page per ad (about 4–5.5 seconds each); after search and paging overhead the default 180 s delivers about 25 Full Search ads per keyword, and at 600 s time is no longer the limit for the default 60 cards. Raise this for larger Full Search results.",
"default": 180
}
}
},
"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
}
}
}
}
}
}
}
}
}
}