{ "openapi": "3.0.1", "info": { "title": "TikTok Ads Scraper - Top Ads & Creative Center", "description": "Scrape TikTok Creative Center: Top Ads by keyword, industry, objective and period, full ad details with landing pages, ad performance analytics, similar ads, the Top Videos ranking and trending hashtags. Export to JSON/CSV/Excel. No login or cookies needed.", "version": "1.0", "x-build-id": "B5Cywbwz0xqP6bgbf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/vulnv~tiktok-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-vulnv-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/vulnv~tiktok-ads-scraper/runs": { "post": { "operationId": "runs-sync-vulnv-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/vulnv~tiktok-ads-scraper/run-sync": { "post": { "operationId": "run-sync-vulnv-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", "required": [ "operation" ], "properties": { "operation": { "title": "⚙️ Operation", "enum": [ "search_ads", "ad_detail", "ad_analytics", "similar_ads", "top_videos", "trending_hashtags" ], "type": "string", "description": "What to scrape. Each operation uses a different input field below:\n\n• Search Top Ads → Keywords (optional) + Ad filters\n• Ad details → Ad IDs / URLs\n• Ad performance analytics → Ad IDs / URLs\n• Similar ads → Ad IDs / URLs (+ Countries)\n• Top Videos ranking → Countries + Top Videos options\n• Trending hashtags → Countries", "default": "search_ads" }, "keywords": { "title": "🔎 Search keywords", "type": "array", "description": "For \"Search Top Ads\". Add one or more keywords (a product, brand or theme). Each keyword is searched independently and duplicates are removed. Leave empty to list the top ads that match your filters without a keyword.", "items": { "type": "string" } }, "adIds": { "title": "🎬 Ad IDs / URLs", "type": "array", "description": "For \"Ad details\", \"Ad performance analytics\" and \"Similar ads\". Paste Creative Center Top Ads URLs (ads.tiktok.com/business/creativecenter/topads//...) or bare ad IDs (e.g. 7215972609221296129), one per line. Every ad row has its ID in the ad_id field.", "items": { "type": "string" } }, "countries": { "title": "🌍 Countries", "type": "array", "description": "Two-letter country codes (e.g. US, GB, JP, DE). Used by \"Similar ads\", \"Top Videos ranking\" and \"Trending hashtags\"; each country is fetched separately. \"Search Top Ads\" searches the whole library and does not use it. The Top Videos ranking is only published for a few countries (US, JP, TH, ID and VN at the time of writing).", "default": [ "US" ], "items": { "type": "string" } }, "maxItems": { "title": "📊 Maximum results per input", "minimum": 0, "maximum": 5000, "type": "integer", "description": "Upper bound on new results per keyword (Search Top Ads), per ad (Similar ads) or per country (Top Videos, Trending hashtags). Top Ads returns at most 400 ads per keyword. Set 0 to fetch all available.", "default": 100 }, "industry": { "title": "🏭 Industry", "type": "string", "description": "For \"Search Top Ads\" and \"Trending hashtags\". An industry name as shown in Creative Center (e.g. Beauty & Personal Care, Games, Apparel & Accessories, Food & Beverage, Tech & Electronics) or its numeric ID (e.g. 14000000000). Leave empty for all industries. Hashtags use the top-level industry." }, "period": { "title": "📅 Period", "enum": [ "7", "30", "180" ], "type": "string", "description": "Time window for \"Search Top Ads\" and the comparison window for \"Ad performance analytics\". Shorter windows return far fewer ads.", "default": "180" }, "objective": { "title": "🎯 Campaign objective", "enum": [ "traffic", "app_installs", "conversions", "video_views", "reach", "lead_generation", "product_sales" ], "type": "string", "description": "Only ads run with this campaign objective. Leave empty for all." }, "performance": { "title": "🏆 Performance band", "enum": [ "top_1_20", "top_21_40", "top_41_60", "top_61_80", "top_81_100" ], "type": "string", "description": "Only ads in this like-performance band. Leave empty for all." }, "adFormat": { "title": "🧩 Ad format", "enum": [ "spark_ads", "non_spark_ads" ], "type": "string", "description": "Spark Ads (boosted organic posts) or non-Spark Ads. Leave empty for both." }, "adLanguage": { "title": "🗣️ Ad language", "type": "string", "description": "Only ads in this language, as a language code: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, ko or zh-Hant. Leave empty for all." }, "sortBy": { "title": "📈 Sort ads by", "enum": [ "for_you", "likes" ], "type": "string", "description": "How Top Ads are ordered.", "default": "for_you" }, "rankingPeriod": { "title": "🗓️ Ranking period", "enum": [ "daily", "weekly", "long_term" ], "type": "string", "description": "For \"Top Videos ranking\". Daily, weekly (ending Sunday) or the long-term ranking.", "default": "daily" }, "rankingDate": { "title": "📆 Ranking date", "type": "string", "description": "For \"Top Videos ranking\". The ranking date as YYYY-MM-DD. Leave empty for the newest published ranking (rankings appear 2-3 days after the day they cover)." }, "videoSort": { "title": "📈 Rank videos by", "enum": [ "views", "engagement_rate", "six_second_view_rate" ], "type": "string", "description": "For \"Top Videos ranking\". The metric the ranking is ordered by.", "default": "views" }, "contentCategories": { "title": "🗂️ Content categories", "type": "array", "description": "For \"Top Videos ranking\". Pick one or more categories. Leave empty to walk the overall ranking plus every category, which returns the most videos.", "items": { "type": "string", "enum": [ "11001", "11002", "11003", "11004", "11005", "11006", "11007", "11008", "11009", "11010", "11011", "11012", "11013", "11014", "11015" ], "enumTitles": [ "Nature & Animals", "Beauty & Personal Care", "Fashion", "Music & Entertainment", "Gaming", "Education & Career", "Sports & Outdoors", "Creativity & Talent", "Family & Relationships", "Food & Drinks", "Vlog & Selfies", "Society", "Lifestyle & Leisure", "Cars & Transport", "Tech & Finance" ] } }, "organicOnly": { "title": "🌱 Organic videos only", "type": "boolean", "description": "For \"Top Videos ranking\". Rank only organic (non-promoted) videos.", "default": false }, "hashtagPeriod": { "title": "#️⃣ Hashtag period", "enum": [ "7", "30", "90" ], "type": "string", "description": "For \"Trending hashtags\". The trend window.", "default": "7" } } }, "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 } } } } } } } } } }