# TikTok Profile & Video Scraper (`headlessagent/tiktok-profile-video-scraper`) Actor Scrape Tiktok profiles and videos. Get clean JSON with profile stats, media URLs, captions, comments, tagged users, and more. - **URL**: https://apify.com/headlessagent/tiktok-profile-video-scraper.md - **Developed by:** [Headless Agent](https://apify.com/headlessagent) (community) - **Categories:** Automation, Social media, Videos - **Stats:** 2 total users, 2 monthly users, 62.5% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $2.90 / 1,000 results 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 Profile & Video Scraper Scrape TikTok **user profiles** and **videos** — no API key or login required. Get clean, formatted JSON with only the important fields. Supports usernames and video URLs as input. ### 🤔 What can TikTok Profile & Video Scraper do? This Actor lets you **extract public data from TikTok profiles and videos** in one place. Just provide usernames or video URLs and get structured results: 👤 Scrape **any public TikTok profile** — bio, followers, following, video count, verification status, and more 🎬 Extract **video data** — description, download URLs (with & without watermark), stats, music info, hashtags, and more 📊 Get **full statistics** — plays, likes, comments, shares, collects, reposts 🎵 Get **music/audio info** — title, artist, album, duration, cover art 🏷️ Get **hashtag data** — ID, title, description, cover image 🖼️ **Best quality media** — automatically picks highest resolution video from bitrate info 🎞️ **Multiple bitrate options** — get all available quality/resolution variants 📦 Download results in **JSON, CSV, XML, or Excel** from the Apify Dataset 🦾 Integrate via **API, webhooks, SDKs** (Python & Node.js), or connect with tools like Zapier, n8n, Make, and more ### ✅ What data can I scrape from TikTok? #### From profiles: - 👤 Username, nickname, bio, bio link - 🌍 Region, language - 📊 Followers count, following count, likes count, video count - ✅ Verification status - 🔒 Private account status - 🖼️ Profile picture URLs (thumbnail, medium, large) - 📅 Account creation timestamp #### From videos: - 🆔 Video ID, description, timestamp - 📥 Download URLs (with & without watermark) - 📊 Stats — plays, likes, comments, shares, collects, reposts - 🎞️ Video metadata — duration, ratio, cover images - 🎵 Music/audio info — title, artist, album, duration, cover - 🏷️ Hashtags with full details - 👤 Author info with stats ### 🔧 How to scrape data from TikTok #### Development ```bash ## Install dependencies (including dev tools) uv sync --group dev ## Format code uv run ruff format . ## Lint code uv run ruff check . ```` #### Running the Actor 1. [Create](https://console.apify.com/sign-up) a free Apify account. 2. Open TikTok Profile & Video Scraper. 3. Add **usernames** and/or **video URLs** — use any combination. 4. Optionally set a **proxy URL** to avoid rate limiting. 5. Click **Save & Start** and wait for the data to be extracted. 6. Download your data in JSON, CSV, XML, Excel, or access it via API. ### ⬇️ Input All fields are optional, but **at least one must be provided**. You can use them independently or together in a single run. | Field | Type | Description | |-------|------|-------------| | `usernames` | `string[]` | TikTok usernames or profile URLs (e.g. `tiktok` or `https://www.tiktok.com/@tiktok`) | | `videoUrls` | `string[]` | TikTok video URLs (e.g. `https://www.tiktok.com/@tiktok/video/7622051063377546527`) | | `proxy` | `string` | Optional proxy URL (`http://` or `socks5://` format) | #### Example input ```json { "usernames": ["tiktok"], "videoUrls": [ "https://www.tiktok.com/@tiktok/video/7622051063377546527", "https://www.tiktok.com/@bellapoarch/video/7611953351915228446" ], "proxy": "http://user:pass@host:port" } ``` ### ⬆️ Output Results are pushed to the Apify Dataset. Each item has a `type` field (`"user"` or `"video"`) so you can easily filter and process them. You can export data in JSON, CSV, XML, Excel, or access it programmatically via the Apify API. #### 👤 User profile data sample ```json { "type": "user", "id": "5831967", "sec_uid": "MS4wLjABAAAA...", "username": "charlidamelio", "nickname": "charli d'amelio", "avatar": "https://p16-sign-va.tiktokcdn.com/...", "avatar_medium": "https://p16-sign-va.tiktokcdn.com/...", "avatar_large": "https://p16-sign-va.tiktokcdn.com/...", "bio": "don't worry i don't get the hype either", "bio_link": "https://www.charlidamelio.com", "region": "US", "language": "en", "created_at": 1560000000, "verified": true, "private": false, "stats": { "followers": "155000000", "following": "1500", "likes": "11500000000", "videos": "2500" } } ``` #### 🎬 Video data sample ```json { "type": "video", "url": "https://www.tiktok.com/@user/video/7590714394581994770", "id": "7590714394581994770", "desc": "caption video #hashtag", "created_at": 1767350925, "download_url": "https://v16-webapp-prime.tiktok.com/...", "download_url_watermark": "https://v16-webapp-prime.tiktok.com/...", "cookies": { "msToken": "abc123...", "tt_chain_token": "U1NMyXsPdRh7Po/DFbOM1Q==", "tt_csrf_token": "t4DToHqI-91S6sZFk0378X0B8ySN-GFQ3-WE", "ttwid": "1|xyz..." }, "author": { "id": "123456", "sec_uid": "MS4wLjABAAAA...", "username": "user", "nickname": "User Name", "verified": false, "avatar": "https://...", "followers": "80000", "following": "27", "likes": "4300000", "videos": "231" }, "stats": { "plays": "9800000", "likes": "103500", "comments": "285", "shares": "37700", "collects": "62702", "reposts": "0" }, "video": { "bitrates": [ { "bitrate": 508441, "fps": 30, "quality_type": 2, "gear_name": "adapt_lowest_1080_1", "codec": "h265_hvc1", "format": "mp4", "width": 1080, "height": 1920, "data_size": "454547", "aweme_url": "https://www.tiktok.com/aweme/v1/play/?...", "cdn_urls": ["https://v16-webapp-prime.tiktok.com/...", "https://v19-webapp-prime.tiktok.com/..."] } ], "duration": 15, "ratio": "720p", "cover": "https://...", "dynamic_cover": "https://...", "origin_cover": "https://..." }, "music": { "id": "7123456789", "title": "original sound", "author": "user", "album": null, "url": "https://...", "cover": "https://...", "duration": 15 }, "hashtags": [ { "id": "123456", "title": "hashtag", "desc": "hashtag description", "cover": "https://..." } ] } ``` ### 🔗 Integrations You can connect TikTok Profile & Video Scraper with almost any cloud service or web app through [Apify integrations](https://apify.com/integrations). Connect with **Zapier, n8n, Make, Slack, Google Sheets, Google Drive, Airbyte, GitHub**, and many more. You can also use [webhooks](https://docs.apify.com/integrations/webhooks) to trigger actions whenever a run finishes — for example, getting a notification or automatically processing the scraped data. ### 🦾 Using the Apify API The Apify [API](https://docs.apify.com/api/v2) gives you programmatic access to TikTok Profile & Video Scraper. You can start runs, fetch datasets, monitor execution, and integrate the scraper into your own workflows. - **Python**: Use the [`apify-client`](https://pypi.org/project/apify-client/) PyPI package - **Node.js**: Use the [`apify-client`](https://www.npmjs.com/package/apify-client) NPM package ### ❓ FAQ #### How do I download videos using the cookies? TikTok's CDN requires cookies from the scrape response to accept download requests. Each video result includes a `cookies` field with the necessary cookies. ##### Using curl ```bash ## Set your cookies from the response COOKIES_STR="msToken=${msToken}; tt_chain_token=${tt_chain_token}; tt_csrf_token=${tt_csrf_token}; ttwid=${ttwid}" OUTPUT="video.mp4" DOWNLOAD_URL="https://v16-webapp-prime.tiktok.com/..." curl -L \ --http2 \ -H "Referer: https://www.tiktok.com/" \ -H "Cookie: ${COOKIES_STR}" \ -o "${OUTPUT}" \ "${DOWNLOAD_URL}" ``` ##### Using Python ```python import requests cookies = { "msToken": "abc123...", "tt_chain_token": "U1NMyXsPdRh7Po/DFbOM1Q==", "tt_csrf_token": "t4DToHqI-91S6sZFk0378X0B8ySN-GFQ3-WE", "ttwid": "1|xyz..." } download_url = "https://v16-webapp-prime.tiktok.com/..." response = requests.get( download_url, cookies=cookies, headers={"Referer": "https://www.tiktok.com/"}, stream=True ) with open("video.mp4", "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) print("Download complete!") ``` > **Note**: Cookies are temporary and may expire. If downloads fail, re-run the scraper to get fresh cookies. #### Can I scrape multiple profiles and videos in one run? Yes. Both input fields (`usernames`, `videoUrls`) accept arrays. You can provide multiple items in each field, and even use both fields together in a single run. Each result will have a `type` field so you can tell them apart. #### What format is the `created_at` / `created_at` timestamp? All timestamps are Unix timestamps (seconds since epoch). You can convert them to a human-readable date using any standard date library or online converter. #### What's the difference between `download_url` and `download_url_watermark`? - `download_url` — video without watermark (highest quality CDN URL) - `download_url_watermark` — video with TikTok watermark > Download using `download_url` requires sending cookies from the response as headers — TikTok's CDN requires this to accept the request. Use the `cookies` field from the video response (see "How do I download videos using the cookies?" above). #### Does the scraper work with private accounts? No. The scraper can only extract data from **public TikTok accounts**. Private profiles will not return profile data, and videos from private accounts are not accessible. #### Can I use a proxy? Yes. The optional `proxy` input field accepts HTTP and SOCKS5 proxy URLs. This is useful to avoid rate limiting or IP blocks when scraping at higher volumes. #### Is it legal to scrape TikTok? This scraper only extracts publicly available data. It does not access private accounts, login credentials, or any data behind authentication. However, scraped results could contain personal data protected by [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation) and other regulations. Ensure you have a legitimate reason for scraping and consult legal counsel if unsure. See also Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). # Actor input Schema ## `usernames` (type: `array`): List of TikTok usernames or profile URLs to scrape. ## `videoUrls` (type: `array`): List of TikTok video URLs (e.g. https://www.tiktok.com/@user/video/1234567890). ## `proxy` (type: `string`): Optional proxy URL (e.g. http://user:pass@host:port or socks5://user:pass@host:port). Useful to avoid rate limiting. ## Actor input object example ```json { "usernames": [ "tiktok" ], "videoUrls": [ "https://www.tiktok.com/@tiktok/video/7622051063377546527", "https://www.tiktok.com/@bellapoarch/video/7611953351915228446" ] } ``` # 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 = { "usernames": [ "tiktok" ], "videoUrls": [ "https://www.tiktok.com/@tiktok/video/7622051063377546527", "https://www.tiktok.com/@bellapoarch/video/7611953351915228446" ] }; // Run the Actor and wait for it to finish const run = await client.actor("headlessagent/tiktok-profile-video-scraper").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 = { "usernames": ["tiktok"], "videoUrls": [ "https://www.tiktok.com/@tiktok/video/7622051063377546527", "https://www.tiktok.com/@bellapoarch/video/7611953351915228446", ], } # Run the Actor and wait for it to finish run = client.actor("headlessagent/tiktok-profile-video-scraper").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 '{ "usernames": [ "tiktok" ], "videoUrls": [ "https://www.tiktok.com/@tiktok/video/7622051063377546527", "https://www.tiktok.com/@bellapoarch/video/7611953351915228446" ] }' | apify call headlessagent/tiktok-profile-video-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=headlessagent/tiktok-profile-video-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Profile & Video Scraper", "description": "Scrape Tiktok profiles and videos. Get clean JSON with profile stats, media URLs, captions, comments, tagged users, and more.", "version": "1.1", "x-build-id": "Kd9KodbzGjD7inQG3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/headlessagent~tiktok-profile-video-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-headlessagent-tiktok-profile-video-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/headlessagent~tiktok-profile-video-scraper/runs": { "post": { "operationId": "runs-sync-headlessagent-tiktok-profile-video-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/headlessagent~tiktok-profile-video-scraper/run-sync": { "post": { "operationId": "run-sync-headlessagent-tiktok-profile-video-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": { "usernames": { "title": "Usernames", "type": "array", "description": "List of TikTok usernames or profile URLs to scrape.", "items": { "type": "string" } }, "videoUrls": { "title": "Video URLs", "type": "array", "description": "List of TikTok video URLs (e.g. https://www.tiktok.com/@user/video/1234567890).", "items": { "type": "string" } }, "proxy": { "title": "Proxy URL", "type": "string", "description": "Optional proxy URL (e.g. http://user:pass@host:port or socks5://user:pass@host:port). Useful to avoid rate limiting." } } }, "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 } } } } } } } } } } ```