{
"openapi": "3.0.1",
"info": {
"title": "TikTok Top Ads Scraper",
"description": "Scrape TikTok Creative Center Top Ads by market, period, industry, objective, language, Spark format and likes tier. Get ad copy, brand, likes, CTR tier, budget, video URLs, landing page and keywords. Export JSON, CSV, Excel.",
"version": "1.1",
"x-build-id": "dOQLRl7dNKP0kMOvA"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/parsebird~tiktok-top-ads-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-parsebird-tiktok-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/parsebird~tiktok-top-ads-scraper/runs": {
"post": {
"operationId": "runs-sync-parsebird-tiktok-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/parsebird~tiktok-top-ads-scraper/run-sync": {
"post": {
"operationId": "run-sync-parsebird-tiktok-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": "Max top ads",
"minimum": 1,
"maximum": 3000,
"type": "integer",
"description": "Maximum number of top ads to save (up to 3,000). The scraper splits your filters into narrower Creative Center lists to collect more than the 20 ads one list shows; very narrow filters can have fewer ads.",
"default": 100
},
"extractDetails": {
"title": "Fetch full ad details",
"type": "boolean",
"description": "Add each ad's landing page, keywords, tags, comments, shares, markets and ad source. Billed as a separate details event per ad.",
"default": false
},
"countryCode": {
"title": "Market",
"enum": [
"",
"US",
"GB",
"DE",
"FR",
"IT",
"ES",
"NL",
"SE",
"RO",
"TR",
"SA",
"AE",
"ZA",
"CA",
"MX",
"BR",
"AR",
"CO",
"AU",
"JP",
"KR",
"ID",
"MY",
"PH",
"SG",
"TH",
"VN",
"PK"
],
"type": "string",
"description": "Country where the ads ran. Leave empty for all markets.",
"default": ""
},
"period": {
"title": "Period",
"enum": [
"7",
"30",
"180"
],
"type": "string",
"description": "Time window of the Top Ads ranking.",
"default": "30"
},
"industry": {
"title": "Industry",
"enum": [
"",
"Apparel & Accessories",
"Apps",
"Appliances",
"Baby, Kids & Maternity",
"Beauty & Personal Care",
"Business Services",
"E-Commerce (Non-app)",
"Education",
"Financial Services",
"Food & Beverage",
"Games",
"Health",
"Home Improvement",
"Household Products",
"Life Services",
"News & Entertainment",
"Pets",
"Sports & Outdoor",
"Tech & Electronics",
"Travel",
"Vehicle & Transportation"
],
"type": "string",
"description": "Keep only ads from one industry. Leave empty for all industries.",
"default": ""
},
"objective": {
"title": "Campaign objective",
"enum": [
"",
"campaign_objective_traffic",
"campaign_objective_app_install",
"campaign_objective_conversion",
"campaign_objective_video_view",
"campaign_objective_reach",
"campaign_objective_lead_generation",
"campaign_objective_product_sales"
],
"type": "string",
"description": "Advertiser's campaign goal. Leave empty for all objectives.",
"default": ""
},
"adLanguage": {
"title": "Ad language",
"pattern": "^([a-zA-Z]{2})?$",
"type": "string",
"description": "Two-letter language code of the ad, e.g. en, es, ja, pt, de. Leave empty for all languages."
},
"adFormat": {
"title": "Ad format",
"enum": [
"",
"Spark ads",
"Non-Spark ads"
],
"type": "string",
"description": "Spark ads are boosted organic TikTok posts; non-Spark ads are uploaded by the advertiser.",
"default": ""
},
"likeTier": {
"title": "Likes",
"enum": [
"",
"1",
"2",
"3",
"4",
"5"
],
"type": "string",
"description": "Keep only ads in one likes tier, as on Creative Center.",
"default": ""
},
"orderBy": {
"title": "Sort by",
"enum": [
"for_you",
"like",
"ctr",
"impression",
"cvr",
"play_2s_rate",
"play_6s_rate"
],
"type": "string",
"description": "Order of the top ads, like the Sort menu on Creative Center.",
"default": "for_you"
},
"keyword": {
"title": "Keyword",
"type": "string",
"description": "Keep only ads whose text or brand name contains these words, e.g. nike or skincare."
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Runs start without a proxy and switch to Apify Proxy automatically if TikTok blocks the 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
}
}
}
}
}
}
}
}
}
}