{ "openapi": "3.0.1", "info": { "title": "Tiktok Trending Videos Scraper", "description": "TikTok Trending Videos Scraper collects data on trending TikTok videos, capturing captions, hashtags, creators, sounds, metrics, and timestamps. Perfect for tracking viral trends, analyzing content performance, researching creators, and automating structured TikTok trend data extraction", "version": "0.1", "x-build-id": "aMQh6CeX1rjJhhPHR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/simpleapi~tiktok-trending-videos-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-simpleapi-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/simpleapi~tiktok-trending-videos-scraper/runs": { "post": { "operationId": "runs-sync-simpleapi-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/simpleapi~tiktok-trending-videos-scraper/run-sync": { "post": { "operationId": "run-sync-simpleapi-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": "🔗 Direct Video URLs (optional — switches off discovery)", "type": "array", "description": "LEAVE THIS EMPTY to scrape trending videos (the normal mode). If you put one or more TikTok video URLs here (e.g. https://www.tiktok.com/@user/video/1234567890123456789), the Actor switches entirely to Video-URL mode: it scrapes exactly those URLs and NOTHING else, and Country / Sort By / Period / Max Items are ignored for that run.", "default": [], "items": { "type": "string" } }, "countryCode": { "title": "🌍 Country Code", "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 feed you want. TikTok geo-targets its feed by the IP address of the request, so this is applied by (a) pinning the Apify Proxy country to this value when Proxy Configuration below has Apify Proxy enabled, and (b) setting the browser locale and timezone. The country TikTok actually served is reported in the log and in every row's `region` field.", "default": "US" }, "sortBy": { "title": "↕️ Sort By", "enum": [ "vv", "like", "comment", "repost" ], "type": "string", "description": "Metric the delivered videos are ranked by, highest first. Views uses TikTok's playCount, Likes uses diggCount, Comments uses commentCount, Shares uses shareCount.", "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 TikTok's anonymous Explore feed only carries a small share of videos less than a week old — with 7 days a large Max Items value can run out of eligible videos (the run then says so explicitly in its status message).", "default": "30" }, "maxItems": { "title": "🔢 Max Items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Exact number of trending videos to deliver (1-1000). The Actor keeps harvesting candidates until it can deliver this many. Ignored in Video-URL mode, which always scrapes every URL you supply.", "default": 10 }, "includeDetailedVideoData": { "title": "📊 Include Detailed Video Data", "type": "boolean", "description": "OFF: each row has the core fields (id, URL, title, cover, duration, publish date, author handle/name, views, likes, comments, shares, bookmarks). ON: each row additionally gets the full caption, hashtags, author id/bio/avatar/verified/follower counts, music metadata, a direct video file URL, video dimensions/bitrate/format, isAd, total engagement and engagement rate.", "default": false }, "proxyConfiguration": { "title": "🌐 Proxy Configuration", "type": "object", "description": "Proxy used for every request (browser + HTTP). KEEP APIFY PROXY ENABLED: TikTok picks the trending region purely from the IP address of the request, so the Country Code above is only honoured when traffic exits from that country. The Actor pins the proxy to your Country Code and automatically escalates to the RESIDENTIAL group when the shared group has no IPs there. Disable it only if you want whatever region the Actor container's own IP resolves to.", "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 } } }, "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 } } } } } } } } } }