{
"openapi": "3.0.1",
"info": {
"title": "TikTok Ad Library Fast Search",
"description": "Fastest TikTok ad intelligence tool. Quick Search mode extracts ads 3-5x faster at $0.005/ad — no detail page visits needed. Full mode adds video URLs, targeting demographics, and reach data at $0.02/ad. Search 10 keywords per run across 30+ EU/EEA countries. JSON, CSV, Excel export.",
"version": "0.1",
"x-build-id": "AbKRxssXsT0BuxtUi"
},
"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.",
"default": false
},
"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": 25
},
"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."
},
"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). Increase this if you are scraping a large number of ads per keyword.",
"default": 300
}
}
},
"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
}
}
}
}
}
}
}
}
}
}