{ "openapi": "3.0.1", "info": { "title": "TikTok Creative Center Top Ads Scraper", "description": "Scrapes top ads from TikTok Creative Center with filters for country, objective, time period, and keyword. Returns each ad as a flat row with engagement metrics and ad details.", "version": "1.0", "x-build-id": "Dx4DlLPWbd4T4dz5V" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~tiktok-creative-center-top-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-tiktok-creative-center-top-ads-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/parseforge~tiktok-creative-center-top-ads-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-tiktok-creative-center-top-ads-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/parseforge~tiktok-creative-center-top-ads-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-tiktok-creative-center-top-ads-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": { "maxItems": { "title": "Maximum ads", "minimum": 1, "maximum": 400, "type": "integer", "description": "How many ads to collect per run. A run returns at most about 20 ads, because TikTok's public Creative Center only returns the first page of results. With a keyword, up to maxItems matching ads from across all industries." }, "countryCode": { "title": "Country Code", "type": "string", "description": "Filter ads by target country (e.g. US, GB, DE, FR, JP). Leave empty for global results.", "default": "US" }, "period": { "title": "Time Period (days)", "minimum": 7, "maximum": 180, "type": "integer", "description": "Time period for top ads ranking: 7, 30, or 180 days.", "default": 7 }, "objectiveKey": { "title": "Campaign Objective", "enum": [ "", "campaign_objective_traffic", "campaign_objective_conversion", "campaign_objective_lead_generation", "campaign_objective_reach", "campaign_objective_video_view", "campaign_objective_product_sales" ], "type": "string", "description": "Filter by campaign objective. Leave empty for all objectives.", "default": "" }, "sortBy": { "title": "Sort By", "enum": [ "popular", "like", "ctr", "reach", "impression", "share", "comment" ], "type": "string", "description": "Sort order for the ads.", "default": "popular" }, "keyword": { "title": "Keyword or industry", "type": "string", "description": "Optional. Keeps only ads whose text, brand or industry mentions every word of the keyword (for example shoes, skincare, running shoes). TikTok has no keyword search in its public Creative Center, so the Actor scans the top ads of every industry and filters them. Works best with time period 180 and no country filter; a run with no match fails without charge." }, "adLanguage": { "title": "Ad Language", "type": "string", "description": "Filter by ad language code (e.g. en, es, ja). Leave empty for all languages." }, "includeDetails": { "title": "Include Details", "type": "boolean", "description": "Fetch enriched details for each ad (keywords, all target countries, objectives). Adds extra requests but only ~10% of ads return detail data due to TikTok API limitations.", "default": false }, "includeLandingPage": { "title": "🔗 Include landing page and engagement", "type": "boolean", "description": "Adds the advertiser's landing page URL and domain, plus comment count, share count, ad source and the voice-over flag. One extra request per ad (shared with Include Details when both are on). Charged only for a row that receives it.", "default": 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 } } } } } } } } } }