{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Library Scraper - Ad Creatives & Ad Spend Data", "description": "Scrape TikTok's Ad Library by keyword, advertiser name, or business ID across any region — get video URLs, cover images, impressions, spend, dates, and rejection info.", "version": "0.1", "x-build-id": "Y9L4FYNtgAPirRC9N" }, "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", "required": [ "search" ], "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 = by advertiser name, 0 = by keyword.", "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 IPv4 proxy URL in the form scheme://username:password@host:port, which routes every request of this run through it. Leaving it blank does not fall back to another proxy: the Actor then connects directly from the Apify compute IP and deliberately ignores the proxy it is otherwise configured with, because that pool is IPv6-only and library.tiktok.com publishes no IPv6 address. Set it only when the compute IP is being rate-limited." }, "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 } } } } } } } } } }