{ "openapi": "3.0.1", "info": { "title": "TikTok Creative Center Top Ads Scraper", "description": "Export public TikTok Creative Center Top Ads by keyword, country, period, industry, objective, language, and format with ad copy, videos, images, and performance signals.", "version": "0.1", "x-build-id": "QXUcyubUsnUHxNIp7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fetch_cat~tiktok-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fetch_cat-tiktok-ads-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/fetch_cat~tiktok-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-fetch_cat-tiktok-ads-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/fetch_cat~tiktok-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-fetch_cat-tiktok-ads-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": { "keywords": { "title": "Keywords", "maxItems": 20, "type": "array", "description": "Optional ad text or brand keywords to search (maximum 20 per run). Split larger lists into separate runs of at most 20 keywords. Leave empty to return top ads for the selected markets.", "items": { "type": "string" } }, "regions": { "title": "Regions / country codes", "type": "array", "description": "TikTok Creative Center country codes such as US, GB, DE, FR, BR, JP, AU. Use one or a few for focused runs.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of ad records to save across all keyword and region combinations.", "default": 20 }, "languages": { "title": "Ad languages", "maxItems": 20, "type": "array", "description": "Optional language codes such as en, es, de, fr, pt, ja (maximum 20 per run). Leave empty for all languages.", "items": { "type": "string" } }, "adFormat": { "title": "Ad format", "type": "string", "description": "Optional TikTok ad format key if you want to narrow results." }, "startUrls": { "title": "Creative Center URLs", "type": "array", "description": "Optional HTTPS ads.tiktok.com Creative Center URLs, as strings or objects with a url field. TikTok profile/video and other unsupported URLs are skipped with a visible warning and RUN_SUMMARY details. If all supplied URLs are unsupported, the run succeeds empty without falling back to unrelated ads. Valid URLs in mixed lists are preserved. Query parameters like keyword, countryCode, and period are used as hints.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "period": { "title": "Time period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Lookback window used by TikTok Creative Center.", "default": "7" }, "industries": { "title": "Industry keys", "maxItems": 20, "type": "array", "description": "Optional TikTok industry/category keys (maximum 20 per run). Leave empty for all industries.", "items": { "type": "string" } }, "objectives": { "title": "Objective keys", "maxItems": 20, "type": "array", "description": "Optional campaign objective keys (maximum 20 per run). Leave empty for all objectives.", "items": { "type": "string" } }, "sortBy": { "title": "Sort by", "enum": [ "for_you", "ctr", "like", "cost" ], "type": "string", "description": "Ranking used by TikTok Creative Center.", "default": "for_you" }, "maxRetries": { "title": "Maximum retries", "minimum": 0, "maximum": 6, "type": "integer", "description": "Retries for temporary network, rate-limit, server, and Creative Center index errors.", "default": 3 }, "runtimeSafetySecs": { "title": "Runtime safety limit", "minimum": 30, "maximum": 270, "type": "integer", "description": "Stops new requests before the platform timeout so completed rows and diagnostics are preserved.", "default": 240 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional Apify Proxy configuration for regions or networks where Creative Center blocks direct requests.", "default": { "useApifyProxy": 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 }, "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 } } } } } } } } } }