{ "openapi": "3.0.1", "info": { "title": "TikTok Data Scraper (Hashtag, Sound & Playlist Analytics)", "description": "Scrape TikTok hashtags, sounds, and playlists with views, posts, creators, engagement, trends, and metadata. Analyze viral content, track hashtag and sound performance, discover trending playlists, research competitors, and uncover insights for TikTok SEO, marketing, and content strategy.", "version": "0.2", "x-build-id": "V4780105jAhgUBcFd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapier~tiktok-data-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapier-tiktok-data-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/scrapier~tiktok-data-scraper/runs": { "post": { "operationId": "runs-sync-scrapier-tiktok-data-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/scrapier~tiktok-data-scraper/run-sync": { "post": { "operationId": "run-sync-scrapier-tiktok-data-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": { "userUrls": { "title": "๐Ÿ”— User URLs, Usernames or IDs", "type": "array", "description": "One or more profiles. Examples: https://www.tiktok.com/@taylorswift ยท taylorswift ยท @taylorswift ยท 107955", "items": { "type": "string" } }, "categories": { "title": "๐Ÿ—‚๏ธ Categories to scrape", "type": "array", "description": "Pick which kinds of content to collect for each profile above. Multiple selections are supported.", "items": { "type": "string", "enum": [ "videos", "favourite_videos", "followers", "following", "search", "user_info" ], "enumTitles": [ "๐Ÿ“น User Videos", "โค๏ธ User Favourite Videos", "๐Ÿ‘ฅ Followers", "๐Ÿซ‚ Following", "๐Ÿ” User Search", "๐Ÿ‘ค User Info" ] }, "default": [ "videos" ] }, "maxUserResults": { "title": "๐Ÿ”ข Max results per category", "minimum": 1, "type": "integer", "description": "Maximum items to fetch per profile / section. Ignored when '๐ŸŒŠ Scrape all results' is enabled.", "default": 10 }, "scrapeAllUserResults": { "title": "๐ŸŒŠ Scrape all available results", "type": "boolean", "description": "Ignore the limit above and collect everything available for each profile.", "default": false }, "videoUrlsComments": { "title": "๐Ÿ”— Video URLs or IDs", "type": "array", "description": "TikTok video URLs or IDs to scrape comments from.", "items": { "type": "string" } }, "commentsPerUrl": { "title": "๐Ÿ”ข Max comments per video", "minimum": 1, "type": "integer", "description": "Maximum comments per video. Ignored when '๐ŸŒŠ Scrape all comments' is on.", "default": 10 }, "scrapeAllComments": { "title": "๐ŸŒŠ Scrape all comments", "type": "boolean", "description": "Collect every available comment per video (slower, more usage).", "default": false }, "repliesPerComment": { "title": "โ†ณ Max replies per comment", "minimum": 0, "type": "integer", "description": "Maximum replies per comment. Set to 0 to skip replies entirely. Ignored when '๐ŸŒŠ Scrape all replies' is on.", "default": 0 }, "scrapeAllReplies": { "title": "๐ŸŒŠ Scrape all replies", "type": "boolean", "description": "Collect every available reply for each comment (slower, more usage).", "default": false }, "trendHashtags": { "title": "#๏ธโƒฃ Hashtags To Track", "type": "array", "description": "Hashtag names or URLs to include in the trend batch. Example: dance or https://www.tiktok.com/hashtag/dance", "items": { "type": "string" } }, "trendHashtagRegions": { "title": "๐ŸŒ Regions For Hashtag Trends (multi-region loop)", "type": "array", "description": "One or more 2-letter region codes. Each hashtag above is looped across EVERY region listed here in the same run, widening geographic trend coverage. Example: [\"US\",\"GB\",\"IN\"]. Also accepts the legacy single 'hashtagRegion' string. Leave empty for US only.", "items": { "type": "string" } }, "videosPerHashtag": { "title": "๐Ÿ”ข Max videos per hashtag/region", "minimum": 1, "type": "integer", "description": "Maximum videos per hashtag, per region. Ignored when '๐ŸŒŠ Scrape all hashtag videos' is on.", "default": 10 }, "scrapeAllHashtagVideos": { "title": "๐ŸŒŠ Scrape all hashtag videos", "type": "boolean", "description": "Collect every available video for each hashtag/region combination (slower, more usage).", "default": false }, "trendSounds": { "title": "๐ŸŽต Sounds / Music To Track", "type": "array", "description": "Music/sound URLs or IDs to include in the same trend batch. Also accepts the legacy 'musicUrls' key.", "items": { "type": "string" } }, "videosPerMusic": { "title": "๐Ÿ”ข Max videos per sound", "minimum": 1, "type": "integer", "description": "Maximum videos per sound. Ignored when '๐ŸŒŠ Scrape all sound videos' is on.", "default": 10 }, "scrapeAllMusicVideos": { "title": "๐ŸŒŠ Scrape all sound videos", "type": "boolean", "description": "Collect every available video for each sound (slower, more usage).", "default": false }, "trendPlaylists": { "title": "โ–ถ๏ธ Playlists To Track", "type": "array", "description": "Playlist (mix) IDs to include in the same trend batch. Also accepts the legacy 'playlistIDs' key.", "items": { "type": "string" } }, "videosPerPlaylist": { "title": "๐Ÿ”ข Max videos per playlist", "minimum": 1, "type": "integer", "description": "Maximum videos per playlist. Ignored when '๐ŸŒŠ Scrape all playlist videos' is on.", "default": 10 }, "scrapeAllPlaylistVideos": { "title": "๐ŸŒŠ Scrape all playlist videos", "type": "boolean", "description": "Collect every available video for each playlist (slower, more usage).", "default": false }, "minDiggCount": { "title": "๐Ÿ‘ Minimum Likes (Digg Count)", "minimum": 0, "type": "integer", "description": "Skip trend-batch videos with fewer likes than this. 0 = no minimum.", "default": 0 }, "minPlayCount": { "title": "โ–ถ๏ธ Minimum Plays (View Count)", "minimum": 0, "type": "integer", "description": "Skip trend-batch videos with fewer plays than this. 0 = no minimum.", "default": 0 }, "oldestDate": { "title": "๐Ÿ“… Oldest Publish Date", "type": "string", "description": "Skip trend-batch videos published before this date. Accepts an absolute date (YYYY-MM-DD) or a relative value (e.g. '7 days', '1 month'). Leave empty to disable." }, "excludeKeywords": { "title": "๐Ÿšซ Exclude Keywords (Title / Description)", "type": "array", "description": "Skip trend-batch videos whose title or description contains any of these keywords (case-insensitive).", "items": { "type": "string" } }, "videoDetailsList": { "title": "๐Ÿ”— Video IDs or URLs", "type": "array", "description": "TikTok video IDs or URLs to retrieve full details for.", "items": { "type": "string" } }, "hashtags": { "title": "๐Ÿ—„๏ธ (Legacy) Hashtag names or URLs", "type": "array", "description": "Same as trendHashtags. Used only when trendHashtags is empty.", "items": { "type": "string" } }, "hashtagRegion": { "title": "๐Ÿ—„๏ธ (Legacy) Region", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Same as trendHashtagRegions (single value). Used only when trendHashtagRegions is empty." }, "musicUrls": { "title": "๐Ÿ—„๏ธ (Legacy) Music URLs or IDs", "type": "array", "description": "Same as trendSounds. Used only when trendSounds is empty.", "items": { "type": "string" } }, "playlistIDs": { "title": "๐Ÿ—„๏ธ (Legacy) Playlist IDs", "type": "array", "description": "Same as trendPlaylists. Used only when trendPlaylists is empty.", "items": { "type": "string" } }, "minRequestInterval": { "title": "โฑ๏ธ Minimum delay between requests (seconds)", "minimum": 0, "maximum": 10, "type": "number", "description": "Seconds to wait between consecutive requests. Lower is faster but more likely to be rate-limited.", "default": 1.2 }, "maxRetries": { "title": "๐Ÿ” Max retries per request", "minimum": 0, "maximum": 10, "type": "integer", "description": "How many times to retry a failed/blocked request before giving up.", "default": 3 }, "apiKey": { "title": "๐Ÿ”‘ Premium data key (optional)", "type": "string", "description": "Optional key that lifts the rate limit for faster collection. Leave empty for the free tier.", "default": "" }, "proxyConfiguration": { "title": "๐Ÿ›ก๏ธ Proxy configuration", "type": "object", "description": "By default the scraper runs WITHOUT a proxy. If TikTok blocks the direct connection, it automatically escalates: ๐Ÿ›ก๏ธ datacenter โ†’ ๐Ÿ  residential, then sticks with residential. You can also force a proxy here.", "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 } } }, "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 } } } } } } } } } }