{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Scraper — Creative Center Top Ads", "description": "Scrape TikTok Creative Center Top Ads by country, industry, objective and time window, sorted by likes, CTR, impressions or cost. Each ad has copy, brand, video link, likes, CTR and Spark Ads flag.", "version": "1.0", "x-build-id": "bCTQY5fdqp8RtBFId" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-tiktok-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/khadinakbar~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-tiktok-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/khadinakbar~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-tiktok-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": { "period": { "title": "Time Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window for the Top Ads ranking. Use '7' for past 7 days (hottest creatives right now), '30' for monthly top performers, '180' for long-running winners. Defaults to 7. This is NOT the date range of when ads ran — it's TikTok's ranking window.", "default": "7" }, "country": { "title": "Country", "enum": [ "", "US", "GB", "CA", "AU", "DE", "FR", "JP", "KR", "BR", "IN", "MX", "IT", "ES", "NL", "SE", "NO", "DK", "FI", "PL", "RU", "TR", "SA", "AE", "EG", "ZA", "NG", "ID", "TH", "VN", "MY", "PH", "SG", "TW", "HK", "AR", "CL", "CO", "PE", "IL", "AT", "BE", "CH", "CZ", "HU", "RO", "UA", "KZ", "PK", "BD", "NZ" ], "type": "string", "description": "Two-letter ISO country code filter (e.g. 'US', 'GB', 'JP'). Leave empty for global top ads across all regions. Not a city or region. Country determines which local advertisers surface in results.", "default": "US" }, "industry": { "title": "Industry / Vertical", "enum": [ "All Industries", "Gaming", "E-commerce & Shopping", "Beauty & Personal Care", "Food & Beverage", "Health & Fitness", "Entertainment", "Sports & Outdoors", "Finance", "Education", "Travel", "Business Services", "Fashion & Apparel", "Technology", "Home & Décor", "Parenting & Kids", "Media & Entertainment", "News & Information", "Music" ], "type": "string", "description": "Filter top ads by industry vertical. Use this when researching a specific niche like 'Beauty & Personal Care', 'Gaming', 'E-commerce & Shopping'. Select 'All Industries' for cross-niche top performers. Not a product category — this is TikTok's advertiser vertical classification.", "default": "All Industries" }, "objective": { "title": "Campaign Objective", "enum": [ "All Objectives", "Traffic", "App Install", "Conversions", "Reach", "Video Views", "Lead Generation", "Engagement" ], "type": "string", "description": "Filter ads by the advertiser's stated campaign objective. 'Conversions' surfaces DTC and e-commerce sales ads. 'App Install' for mobile app ads. 'Traffic' for click-focused ads. Select 'All Objectives' for broader coverage. Only one objective can be selected per run.", "default": "All Objectives" }, "adFormat": { "title": "Ad Format", "enum": [ "All Formats", "Spark Ads", "Non-Spark Ads", "Collection Ads" ], "type": "string", "description": "Filter by TikTok ad format. 'Spark Ads' are boosted organic posts (creator partnerships). 'Non-Spark Ads' are traditional paid creative. 'Collection Ads' are multi-product shopping ads. Select 'All Formats' for every type. Not the same as ad placement.", "default": "All Formats" }, "orderBy": { "title": "Sort Order", "enum": [ "For You", "Likes", "CTR", "Impressions", "Cost" ], "type": "string", "description": "How to rank the returned ads. 'For You' is TikTok's recommended mix. 'Likes' sorts by engagement. 'CTR' surfaces highest click-through performers (best for creative research). 'Impressions' sorts by estimated reach. 'Cost' by estimated ad spend. Default 'For You'.", "default": "For You" }, "keyword": { "title": "Keyword Search", "type": "string", "description": "Optional free-text keyword to search across ad creative text, brand names, and CTAs (e.g. 'skincare routine', 'black friday'). Leave empty for no keyword filter. This is a Creative Center search term, NOT a hashtag or campaign ID.", "default": "" }, "maxResults": { "title": "Max Ads to Return", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of ads to extract (1–500). TikTok Creative Center typically surfaces 20–100 ads per filter combination without login; scraper auto-scrolls to load more. Use 20–50 for quick creative research, 200+ for bulk swipe-file building. Each ad is billed at $0.003.", "default": 50 }, "responseFormat": { "title": "Response Format", "enum": [ "detailed", "concise" ], "type": "string", "description": "Output detail level. 'concise' returns only the essential fields (14 keys, ~250 tokens/ad) — ideal for AI agents and quick swipe files. 'detailed' returns all 20+ fields including advertiser ID, HD video URL, CTR/CVR numbers, days running, and tags (~450 tokens/ad). Default is 'detailed'.", "default": "detailed" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for reliability. Residential Apify Proxy is the default because TikTok Creative Center commonly stalls or blocks generic proxy traffic. Keep the default unless you have a tested custom proxy configuration.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }