# TikTok Video Downloader - Download Videos & Metadata (`vnx0/tiktok-downloader`) Actor Download TikTok videos, extract metadata, and scrape profiles, trending feeds, hashtags, and sounds. Get video files, stats, author info, and music data with one click. - **URL**: https://apify.com/vnx0/tiktok-downloader.md - **Developed by:** [Vnx0](https://apify.com/vnx0) (community) - **Categories:** Videos, Social media, Automation - **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 video scrapeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## TikTok Video Downloader Download TikTok videos as MP4 files and extract comprehensive metadata from any TikTok video, profile, trending feed, hashtag, or sound. Scrape bulk videos, save video files and thumbnails, and get structured JSON data — all in one run. ### Why use TikTok Video Downloader? - **Download actual MP4 video files** — not just metadata. Get video files saved directly to your Key-Value Store - **Bulk video downloader** — scrape and download multiple videos from profiles, trending feeds, hashtags, and sounds in a single run - **Multiple scraping modes** — single video, user profile, trending feed, hashtag, or sound - **Fast files-only mode** — skip metadata extraction and just download video/cover files directly (faster, cheaper) - **Auto URL detection** — paste any TikTok link and the actor automatically detects the type - **Built-in proxy support** — uses Apify Proxy with residential IPs to bypass rate limits - **Anti-bot bypass** — powered by Playwright browser automation with stealth mode - **Structured JSON output** — clean dataset with video stats, author info, music details, and hashtags ### What data can TikTok Video Downloader extract? | Field | Type | Description | |-------|------|-------------| | Video URL | String | Full TikTok video URL | | Video file | MP4 (binary) | Downloaded video file in Key-Value Store | | Cover image | JPEG/PNG (binary) | Video thumbnail in Key-Value Store (optional) | | Description | String | Video caption or text | | Author username | String | TikTok @username | | Author nickname | String | Display name | | Verified | Boolean | Whether the author is verified | | Avatar URL | String | Author profile picture URL | | Play count | Number | Total video views | | Like count | Number | Total likes | | Share count | Number | Total shares | | Comment count | Number | Total comments | | Music title | String | Audio/song title | | Music author | String | Audio/song creator | | Music URL | String | Direct audio file URL | | Hashtags | Array | Hashtags used in the video | | Duration | Number | Video length in seconds | | Create time | String | Video upload timestamp | ### Use Cases - **Social media managers** — bulk download competitor content and trending TikTok videos for analysis - **Marketers and researchers** — scrape TikTok engagement metrics, trending content, and hashtag performance data - **Data scientists** — collect structured TikTok metadata for sentiment analysis, trend forecasting, and research - **Content creators** — back up your own TikTok videos and track engagement over time - **Developers** — integrate TikTok data into your apps via structured JSON API output ### How to scrape TikTok videos 1. **Add your TikTok URL** — paste a video, profile, hashtag, or trending link 2. **Choose a mode** — auto-detect, single video, profile, trending, hashtag, or sound 3. **Configure downloads** — enable video and/or cover image downloads 4. **Run the actor** — results are saved to the dataset and files to Key-Value Store #### Supported URL formats - **Single video**: `https://www.tiktok.com/@username/video/123456` - **User profile**: `https://www.tiktok.com/@username` - **Hashtag**: `https://www.tiktok.com/t/hashtag` - **Trending**: Use mode "trending" (no URL needed) ### How much does it cost? This actor uses **Pay Per Event** pricing at **$0.003 per video scraped**. You only pay for what you use — Apify compute costs are billed separately. | Videos | Actor Cost | |--------|------------| | 100 | $0.30 | | 1,000 | $3.00 | | 10,000 | $30.00 | > The free Apify tier includes **$5 free credit** to get started. Downloading video files uses additional compute resources — use files-only mode when you only need downloads, or disable downloads for metadata-only scraping to save on costs. ### Input See the **Input** tab for full configuration options. Key settings: - **Start URLs** — TikTok URLs to scrape (video, profile, or hashtag links) - **Scraping Mode** — auto-detect, single video, profile, trending, hashtag, or sound - **Output mode** — "full" for metadata + downloads, "files_only" for downloads only (faster) - **Max results** — limit how many videos to scrape per run (0 = unlimited) - **Download videos** — save MP4 files to Key-Value Store (enabled by default) - **Download covers** — save thumbnail images to Key-Value Store (disabled by default) - **Proxy configuration** — recommended for large scraping jobs. Use residential proxies for best results. ### Output Each video is pushed to the dataset as a JSON object. You can download the dataset in JSON, CSV, or Excel format. Downloaded video files are stored in the **Key-Value Store** with keys like `video-1234567890.mp4`. #### Sample output ```json { "id": "7106594312292453675", "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675", "description": "Check out TikTok's Minecraft community!", "author": { "id": "107955", "username": "tiktok", "nickname": "TikTok", "verified": true }, "stats": { "playCount": 561600, "likeCount": 98700, "commentCount": 1342 }, "music": { "title": "original sound", "author": "TikTok" }, "videoKey": "video-7106594312292453675" } ```` ### Tips - **Use residential proxies** for best results — TikTok aggressively blocks datacenter IPs - **Use files-only mode** to skip metadata when you just need downloads — saves time and cost - **Disable video downloads** for metadata-only scraping — saves time and storage costs - **Start with maxItems: 10** when testing a new profile or hashtag - **Trending mode** does not require a start URL — just select "trending" as the mode ### FAQ **Is this actor legal?** This actor only extracts publicly available data that TikTok displays to any visitor. It does not access private accounts, messages, or any authenticated content. Always ensure your use case complies with TikTok's Terms of Service and applicable data protection regulations in your jurisdiction. **Why do I need a proxy?** TikTok has strong anti-bot protections. Using Apify's residential proxy rotation helps avoid rate limits and CAPTCHAs. Without a proxy, large scraping jobs may get blocked. **Can I bulk download all videos from a TikTok profile?** Yes. Select "profile\_videos" mode and paste a profile URL. The actor will iterate through all videos on the profile. Use maxItems to limit how many to download. **How to scrape TikTok trending videos?** Select "trending" mode — no URL is needed. The actor will fetch the current trending feed and scrape videos from it. **Can I scrape videos by hashtag?** Yes. Paste a hashtag URL like `https://www.tiktok.com/t/minecraft` and select "hashtag\_videos" mode to scrape all videos under that hashtag. **Why is my video download empty?** Some TikTok videos may have download restrictions or the video URL may have expired. Try re-running the actor or enabling proxy rotation for better reliability. **What's the difference between "full" and "files\_only" mode?** "Full" mode scrapes metadata (description, stats, author info, music, etc.) and pushes it to the dataset, plus downloads files. "Files\_only" mode skips all metadata extraction — it just downloads the MP4 and/or cover files directly. Use files\_only when you only need the video files and want faster, cheaper runs. **Can I scrape private profiles?** No. This actor only works with publicly available TikTok content. ### Support If you encounter any issues, please visit the Issues tab and report the problem. We actively monitor and respond to all issues. # Actor input Schema ## `startUrls` (type: `array`): TikTok video URLs (e.g., https://www.tiktok.com/@user/video/123), profile URLs (e.g., https://www.tiktok.com/@username), hashtag URLs, or sound URLs. ## `mode` (type: `string`): What to scrape ## `maxItems` (type: `integer`): Maximum number of videos to scrape per profile/hashtag/sound/trending. Set to 0 for unlimited. ## `downloadVideos` (type: `boolean`): Download and save video (.mp4) files to the Key-Value Store. ## `downloadCovers` (type: `boolean`): Download and save video cover/thumbnail images to the Key-Value Store. ## `outputMode` (type: `string`): What to output. 'full' scrapes metadata and pushes to dataset plus downloads files. 'files\_only' skips metadata — just downloads video/cover files directly (faster). ## `proxyConfiguration` (type: `object`): Apify Proxy or custom proxy configuration. Using proxies is recommended for large scraping jobs. ## `msToken` (type: `string`): TikTok msToken cookie for improved reliability. Get it from your browser cookies on tiktok.com. Leave empty to auto-generate. ## Actor input object example ```json { "startUrls": [ { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" } ], "mode": "auto", "maxItems": 50, "downloadVideos": true, "downloadCovers": false, "outputMode": "full", "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `dataset` (type: `string`): Dataset containing video metadata, stats, and author info. ## `videos` (type: `string`): Video files saved in the Key-Value Store. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("vnx0/tiktok-downloader").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [{ "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" }] } # Run the Actor and wait for it to finish run = client.actor("vnx0/tiktok-downloader").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" } ] }' | apify call vnx0/tiktok-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=vnx0/tiktok-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Video Downloader - Download Videos & Metadata", "description": "Download TikTok videos, extract metadata, and scrape profiles, trending feeds, hashtags, and sounds. Get video files, stats, author info, and music data with one click.", "version": "0.0", "x-build-id": "EaZg27TFwjlsumC4l" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/vnx0~tiktok-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-vnx0-tiktok-downloader", "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/vnx0~tiktok-downloader/runs": { "post": { "operationId": "runs-sync-vnx0-tiktok-downloader", "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/vnx0~tiktok-downloader/run-sync": { "post": { "operationId": "run-sync-vnx0-tiktok-downloader", "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": [ "startUrls" ], "properties": { "startUrls": { "title": "Start URLs", "type": "array", "description": "TikTok video URLs (e.g., https://www.tiktok.com/@user/video/123), profile URLs (e.g., https://www.tiktok.com/@username), hashtag URLs, or sound URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "mode": { "title": "Scraping Mode", "enum": [ "auto", "single_video", "profile_videos", "trending", "hashtag_videos", "sound_videos" ], "type": "string", "description": "What to scrape", "default": "auto" }, "maxItems": { "title": "Max results", "minimum": 0, "maximum": 1000, "type": "integer", "description": "Maximum number of videos to scrape per profile/hashtag/sound/trending. Set to 0 for unlimited.", "default": 50 }, "downloadVideos": { "title": "Download video files", "type": "boolean", "description": "Download and save video (.mp4) files to the Key-Value Store.", "default": true }, "downloadCovers": { "title": "Download cover images", "type": "boolean", "description": "Download and save video cover/thumbnail images to the Key-Value Store.", "default": false }, "outputMode": { "title": "Output mode", "enum": [ "full", "files_only" ], "type": "string", "description": "What to output. 'full' scrapes metadata and pushes to dataset plus downloads files. 'files_only' skips metadata — just downloads video/cover files directly (faster).", "default": "full" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or custom proxy configuration. Using proxies is recommended for large scraping jobs.", "default": { "useApifyProxy": true } }, "msToken": { "title": "msToken (optional)", "type": "string", "description": "TikTok msToken cookie for improved reliability. Get it from your browser cookies on tiktok.com. Leave empty to auto-generate." } } }, "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 } } } } } } } } } } ```