{ "openapi": "3.0.1", "info": { "title": "TikTok Trending Videos Scraper", "description": "TikTok Trending Videos Scraper collects videos trending on TikTok by country: views, likes, comments, shares, bookmarks, author, caption and date. Sort by metric, filter last 7 or 30 days, or scrape your own video links. Export to JSON, CSV or Excel, or use the API.", "version": "0.1", "x-build-id": "8sVi0oEwFWzeoqh27" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/socialdataapi~tiktok-trending-videos-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-socialdataapi-tiktok-trending-videos-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/socialdataapi~tiktok-trending-videos-scraper/runs": { "post": { "operationId": "runs-sync-socialdataapi-tiktok-trending-videos-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/socialdataapi~tiktok-trending-videos-scraper/run-sync": { "post": { "operationId": "run-sync-socialdataapi-tiktok-trending-videos-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": { "videoUrls": { "title": "🔗 Video links (optional, replaces trending mode)", "type": "array", "description": "Leave this empty to scrape trending videos (the normal mode). If you add TikTok video links (for example https://www.tiktok.com/@user/video/1234567890123456789), the run scrapes exactly those videos instead, one row per video. Sort by, Period and Max items do not apply in this mode; Country is still used to pick the proxy country. Links that are not TikTok links are skipped and not charged, and a video listed twice is scraped once. Free plan: up to 20 videos per run (all video links together) and 200 per month; paid plans have no limit.", "default": [], "items": { "type": "string" } }, "countryCode": { "title": "📍 Country", "enum": [ "AU", "BR", "CA", "EG", "FR", "DE", "ID", "IL", "IT", "JP", "MY", "PH", "RU", "SA", "SG", "KR", "ES", "TW", "TH", "TR", "AE", "GB", "US", "VN" ], "type": "string", "description": "Country whose trending videos you want. TikTok shows trending videos based on where the connection comes from, so this country is honoured when the Apify proxy below is turned on (the run then uses a proxy in this country). The country TikTok actually served is written to every trending row as the served region and shown in the log.", "default": "US" }, "sortBy": { "title": "🔃 Sort by", "enum": [ "vv", "like", "comment", "repost" ], "type": "string", "description": "Order of the delivered videos, highest first: by view count, like count, comment count or share count. The ranking is applied to the trending videos collected in this run.", "default": "vv" }, "period": { "title": "📅 Period", "enum": [ "7", "30" ], "type": "string", "description": "Only keep videos published within the last 7 or 30 days. 30 days is the default because only a small share of trending videos is less than a week old: with 7 days a large Max items value can run out of eligible videos, and the run then says so in its status message.", "default": "30" }, "maxItems": { "title": "🔢 Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many trending videos to deliver (1-1000). The run keeps collecting until it has this many or reaches its time limit; if fewer are available, it delivers what it found and says so in the status message. Not used when Video links are given. Free plan: up to 20 videos per run and 200 per month; paid plans have no limit.", "default": 10 }, "includeDetailedVideoData": { "title": "✅ Include detailed video data", "type": "boolean", "description": "Off: each row has the core fields (video ID and link, caption as title, cover image, duration, publish date, author handle and name, views, likes, comments, shares, bookmarks). On: each row also gets the full caption, hashtags, author ID, bio, avatar, verified badge and follower, following, likes and video counts, music details, a direct video file link, video size, quality and format, the ad flag, total engagement and engagement rate.", "default": false }, "proxyConfiguration": { "title": "🌐 Proxy configuration", "type": "object", "description": "Proxy used for every request. Keep the Apify proxy on: TikTok picks the trending country from where the connection comes from, so Country above is only honoured through a proxy in that country. The run looks for a working proxy in your country and may switch to residential proxies (in your country) when the default proxies have none or stop returning new videos; residential traffic can cost more on your Apify plan. If you choose specific proxy groups, the run may still switch to residential proxies for later new connections. Your own proxy URLs are used as given. Turn the proxy off only if you want whatever country this run's own connection gets.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }