{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper - Ad Creatives, Videos & Dates", "description": "Search the TikTok Ads Library by advertiser name, business ID or ad ID in any supported region. Get each ad's creative format, video and image URLs, first and last shown dates, audience range and rejection info as JSON, or a free count of matching ads.", "version": "0.2", "x-build-id": "OHH7tfDmUWmjXAVT6" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/s-r~tiktok-ads-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-s-r-tiktok-ads-library", "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/s-r~tiktok-ads-library/runs": { "post": { "operationId": "runs-sync-s-r-tiktok-ads-library", "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/s-r~tiktok-ads-library/run-sync": { "post": { "operationId": "run-sync-s-r-tiktok-ads-library", "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": { "search": { "title": "Search query", "type": "string", "description": "Advertiser name or keyword (e.g. \"nike\", \"korean skincare\"). One of search / ad_id / adv_biz_ids is required." }, "ad_id": { "title": "Ad ID", "type": "string", "description": "Look up one ad by its ID. This short-circuits the whole run: nothing is fetched from TikTok and the search query, region, dates, sort, limit and offset are all ignored. The single row it returns carries the ad id and a deeplink and no ad content, because TikTok publishes no ad-detail API to read it from." }, "adv_biz_ids": { "title": "Advertiser business ID", "type": "string", "description": "TikTok's own advertiser business ID. It is sent in the search body next to the query, so TikTok narrows on it rather than the rows being filtered here. It does not replace Search query: whatever is in that box is still sent alongside, so clear it if you want the advertiser on its own. One of search, ad_id or this is needed to start a run." }, "region": { "title": "Region", "enum": [ "all", "NL", "DE", "BE", "FR", "GB", "ES", "IT", "AT", "CH", "PL", "SE", "DK", "NO", "FI", "PT", "IE", "AU", "CA", "NZ", "JP", "KR", "BR", "MX", "IN", "TR", "ZA", "AR", "CL", "CO", "EG", "SA", "AE", "IL", "SG", "MY", "TH", "PH", "ID", "VN", "TW", "HK" ], "type": "string", "description": "ISO country code or 'all'. Note: TikTok Ad Library does NOT support region=US — use 'all' to include US ads in the global result set.", "default": "all" }, "query_type": { "title": "Query type", "enum": [ "1", "0" ], "type": "string", "description": "1 = advertiser name (default). 0 passes through the legacy keyword mode; TikTok may return unrelated advertisers.", "default": "1" }, "sort": { "title": "Sort order", "enum": [ "last_shown_date,desc", "last_shown_date,asc", "first_shown_date,desc", "first_shown_date,asc", "impression,desc", "impression,asc" ], "type": "string", "description": "Order results by recency or impression count.", "default": "last_shown_date,desc" }, "ad_status": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Stopped creative is a record of what an advertiser tried and dropped, and it is usually the larger half. Measured on one Dutch retailer: 12 ads running against 681 stopped.", "default": "active" }, "only_total": { "title": "Count only", "type": "boolean", "description": "Return one row with how many ads match and no ads at all. Costs one request and no per-ad charge. TikTok caps the reported figure at 5000, and the row says whether the number is exact or a floor.", "default": false }, "start_date": { "title": "Start date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Lower bound of the search window, written YYYY-MM-DD. It becomes the start_time parameter on TikTok's own search call, so TikTok applies it and a narrower window means fewer pages to walk. Left empty it defaults to one year before the run. An Ad ID lookup ignores it." }, "end_date": { "title": "End date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Upper bound of the search window, written YYYY-MM-DD. Like the lower bound it is sent as a parameter on TikTok's own search call rather than applied to the rows afterwards. Left empty it defaults to the moment the run starts, and an Ad ID lookup ignores it." }, "limit": { "title": "Number of ads", "minimum": 1, "maximum": 500, "type": "integer", "description": "How many ads to collect. TikTok serves 12 per response, so higher values walk the cursor further and take longer.", "default": 20 }, "offset": { "title": "Pagination offset", "minimum": 0, "type": "integer", "description": "Result offset for pagination.", "default": 0 }, "proxy_url": { "title": "Proxy URL (optional, advanced)", "type": "string", "description": "Optional HTTP or HTTPS proxy URL with a DNS hostname. Its credentials are used only for this request. Blank uses the configured transport." }, "search_id": { "title": "Resume cursor (optional)", "type": "string", "description": "Continue a previous run from the `_next_search_id` value it wrote on its rows, paired with the Pagination offset from the same rows. The Actor already walks the cursor by itself up to Number of ads, so this is only for going past where an earlier run stopped, not for reaching a higher count in one go. Leave empty to start a fresh search." } } }, "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 } } } } } } } } } }