# TikTok Scraper Pro (`netdesignr/tiktok-scraper-pro`) Actor Scrape TikTok videos from profiles, video URLs, search, hashtags, and sounds with stronger diagnostics, simpler pricing, and cleaner output. - **URL**: https://apify.com/netdesignr/tiktok-scraper-pro.md - **Developed by:** [Netdesignr](https://apify.com/netdesignr) (community) - **Categories:** Social media - **Stats:** 4 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 Scraper Pro Scrape TikTok videos from profiles, direct video URLs, searches, hashtags, and music pages with clearer diagnostics, simpler pricing, and a cleaner output schema than older all-in-one actors. ### Why This Actor Exists Many TikTok scrapers are broad but hard to reason about: - pricing gets complicated fast - filter features are sold as add-ons - empty runs are hard to diagnose - outputs vary by surface and need cleanup before they are useful `TikTok Scraper Pro` is built to be easier to run in production: - one normalized video schema across supported surfaces - honest `accessStatus` diagnostics per target - built-in date and popularity filters - optional session cookies for degraded public pages - one simple pay-per-event model for emitted videos ### Supported Surfaces - TikTok usernames and profile URLs - Direct TikTok video URLs - TikTok search result pages - TikTok hashtag pages - TikTok music and sound pages ### What Data Can I Extract With TikTok Scraper Pro? | Identity | Content | Media | Metrics | Context | | --- | --- | --- | --- | --- | | Video URL | Description | Cover URL | Views | Source surface | | Video ID | Hashtags | Dynamic cover URL | Likes | Source input | | Author username | Mentions | Play URL | Comments | Access status | | Author display name | Create time | Download URL when available | Shares | Extraction method | | Author ID | Sound title | Width and height | Saves | Warnings | | Author verified flag | Sound author | Duration | | Optional profile snapshot | ### Input #### Core fields - `startUrls`: mix profile URLs, usernames, direct video URLs, hashtag URLs, search URLs, and music URLs - `searchQueries`: convenience field for keyword searches - `hashtags`: convenience field for hashtag runs - `musicUrls`: convenience field for sounds and music pages - `maxItemsPerTarget`: per-target video cap - `dateFrom`, `dateTo`: built-in date filtering - `minViews`, `minLikes`, `minComments`: built-in popularity filters - `extractionMode`: `fast`, `balanced`, or `full` - `includeProfileDetails` - `includeDownloadUrls` - `sessionCookieHeader` - `proxyConfiguration` - `emptyRunPolicy` - `debugMode` #### Example input ```json { "startUrls": [ "nike", "https://www.tiktok.com/search?q=marketing", "https://www.tiktok.com/music/original-sound-6689804660171082501" ], "maxItemsPerTarget": 10, "dateFrom": "30 days", "minLikes": 100, "includeProfileDetails": true, "includeDownloadUrls": true, "extractionMode": "balanced" } ```` ### Output Each dataset item is one normalized TikTok video record. ```json { "recordType": "video", "sourceType": "search", "sourceInput": "https://www.tiktok.com/search?q=marketing", "canonicalUrl": "https://www.tiktok.com/@ceekmarketing/video/7608320917227179286", "id": "7608320917227179286", "description": "Save these content trends for your next content day...", "hashtags": ["socialmedia", "contenttrends", "marketing"], "mentions": [], "createTime": "2026-02-18T12:11:03.000Z", "durationSeconds": 48, "coverUrl": "https://...", "videoUrl": "https://...", "downloadUrl": "https://...", "commentCount": 12, "likeCount": 500, "shareCount": 20, "viewCount": 20000, "authorUsername": "ceekmarketing", "authorDisplayName": "Ceek Marketing", "musicTitle": "Original Sound", "accessStatus": "success", "extractionMethod": "browser_api", "warnings": [], "scrapedAt": "2026-03-26T13:30:00.000Z" } ``` ### Diagnostics This actor does not silently flatten blocked or degraded targets into fake success. Each target is summarized with: - `success` - `partial_result` - `empty_result` - `login_wall` - `rate_limited` - `private_or_unavailable` - `not_found` - `unsupported_surface` - `unknown_error` It also persists: - `RUN_META` - `SUMMARY.json` ### API Examples #### JavaScript ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('netdesignr/tiktok-scraper-pro').call({ searchQueries: ['marketing'], maxItemsPerTarget: 5, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ["APIFY_TOKEN"]) run = client.actor("netdesignr/tiktok-scraper-pro").call(run_input={ "hashtags": ["travel"], "maxItemsPerTarget": 5, }) items = client.dataset(run["defaultDatasetId"]).list_items().items print(items) ``` #### cURL ```bash curl -X POST "https://api.apify.com/v2/acts/netdesignr~tiktok-scraper-pro/runs?token=$APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "startUrls": ["https://www.tiktok.com/search?q=marketing"], "maxItemsPerTarget": 5 }' ``` ### Positioning Against Older TikTok Actors This actor is designed to compete on: - simpler pricing - stronger diagnostics - cleaner schema - built-in filtering instead of paid filter add-ons - more honest handling of degraded public surfaces ### Current Limitations - TikTok profile, hashtag, and music collection can degrade on aggressive anti-bot conditions - follower and following graph extraction is intentionally out of scope for v1 - full comment trees are out of scope for v1 - subtitles are not guaranteed across all surfaces yet ### Responsible Use Use this actor only for data you are permitted to access and process. Respect TikTok terms, local law, privacy obligations, and your downstream usage responsibilities. # Actor input Schema ## `startUrls` (type: `array`): TikTok usernames, profile URLs, direct video URLs, hashtag URLs, search URLs, or music URLs. Usernames such as nike also work here. ## `searchQueries` (type: `array`): Optional convenience field for keyword searches. Each query is converted into a TikTok search URL automatically. ## `hashtags` (type: `array`): Optional convenience field for hashtag collection. Values can include or omit the leading #. ## `musicUrls` (type: `array`): Optional convenience field for TikTok music or sound URLs. ## `maxItemsPerTarget` (type: `integer`): Maximum number of TikTok videos to emit for each target. ## `dateFrom` (type: `string`): Only keep videos created on or after this value. Accepts ISO dates like 2026-03-01 or relative values like 7 days or 2 weeks. ## `dateTo` (type: `string`): Only keep videos created on or before this value. Accepts ISO dates or relative values. ## `minViews` (type: `integer`): Drop videos below this play count threshold. ## `minLikes` (type: `integer`): Drop videos below this like count threshold. ## `minComments` (type: `integer`): Drop videos below this comment count threshold. ## `extractionMode` (type: `string`): Fast prefers lightweight detail scraping, balanced enables stronger browser API capture for harder surfaces, and full keeps scrolling longer for broader collection. ## `includeProfileDetails` (type: `boolean`): Attach a normalized profile snapshot when TikTok exposes it. ## `includeDownloadUrls` (type: `boolean`): Keep download URLs when TikTok exposes them in the source payload. ## `sessionCookieHeader` (type: `string`): Optional raw Cookie header copied from a logged-in browser session. Helps when TikTok degrades public surfaces. ## `proxyConfiguration` (type: `object`): Optional proxy configuration for region-sensitive or anti-bot-heavy targets. ## `emptyRunPolicy` (type: `string`): How the actor should exit when targets were reachable but no videos were emitted after retry. ## `debugMode` (type: `boolean`): Include extra runtime warnings for troubleshooting. ## Actor input object example ```json { "startUrls": [ "nike", "https://www.tiktok.com/search?q=marketing", "https://www.tiktok.com/music/original-sound-6689804660171082501" ], "maxItemsPerTarget": 12, "extractionMode": "balanced", "includeProfileDetails": true, "includeDownloadUrls": true, "emptyRunPolicy": "retry_then_warn", "debugMode": false } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `detailed` (type: `string`): No description ## `engagement` (type: `string`): No description ## `media` (type: `string`): No description ## `diagnostics` (type: `string`): No description # 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": [ "nike", "https://www.tiktok.com/search?q=marketing", "https://www.tiktok.com/music/original-sound-6689804660171082501" ] }; // Run the Actor and wait for it to finish const run = await client.actor("netdesignr/tiktok-scraper-pro").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": [ "nike", "https://www.tiktok.com/search?q=marketing", "https://www.tiktok.com/music/original-sound-6689804660171082501", ] } # Run the Actor and wait for it to finish run = client.actor("netdesignr/tiktok-scraper-pro").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": [ "nike", "https://www.tiktok.com/search?q=marketing", "https://www.tiktok.com/music/original-sound-6689804660171082501" ] }' | apify call netdesignr/tiktok-scraper-pro --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=netdesignr/tiktok-scraper-pro", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Scraper Pro", "description": "Scrape TikTok videos from profiles, video URLs, search, hashtags, and sounds with stronger diagnostics, simpler pricing, and cleaner output.", "version": "0.1", "x-build-id": "51mWGhqEUS8tlGuie" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/netdesignr~tiktok-scraper-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-netdesignr-tiktok-scraper-pro", "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/netdesignr~tiktok-scraper-pro/runs": { "post": { "operationId": "runs-sync-netdesignr-tiktok-scraper-pro", "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/netdesignr~tiktok-scraper-pro/run-sync": { "post": { "operationId": "run-sync-netdesignr-tiktok-scraper-pro", "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": { "startUrls": { "title": "Start URLs", "type": "array", "description": "TikTok usernames, profile URLs, direct video URLs, hashtag URLs, search URLs, or music URLs. Usernames such as nike also work here.", "items": { "type": "string" } }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Optional convenience field for keyword searches. Each query is converted into a TikTok search URL automatically.", "items": { "type": "string" } }, "hashtags": { "title": "Hashtags", "type": "array", "description": "Optional convenience field for hashtag collection. Values can include or omit the leading #.", "items": { "type": "string" } }, "musicUrls": { "title": "Music URLs", "type": "array", "description": "Optional convenience field for TikTok music or sound URLs.", "items": { "type": "string" } }, "maxItemsPerTarget": { "title": "Max videos per target", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of TikTok videos to emit for each target.", "default": 12 }, "dateFrom": { "title": "Date from", "type": "string", "description": "Only keep videos created on or after this value. Accepts ISO dates like 2026-03-01 or relative values like 7 days or 2 weeks." }, "dateTo": { "title": "Date to", "type": "string", "description": "Only keep videos created on or before this value. Accepts ISO dates or relative values." }, "minViews": { "title": "Minimum views", "minimum": 0, "type": "integer", "description": "Drop videos below this play count threshold." }, "minLikes": { "title": "Minimum likes", "minimum": 0, "type": "integer", "description": "Drop videos below this like count threshold." }, "minComments": { "title": "Minimum comments", "minimum": 0, "type": "integer", "description": "Drop videos below this comment count threshold." }, "extractionMode": { "title": "Extraction mode", "enum": [ "fast", "balanced", "full" ], "type": "string", "description": "Fast prefers lightweight detail scraping, balanced enables stronger browser API capture for harder surfaces, and full keeps scrolling longer for broader collection.", "default": "balanced" }, "includeProfileDetails": { "title": "Include profile snapshot", "type": "boolean", "description": "Attach a normalized profile snapshot when TikTok exposes it.", "default": true }, "includeDownloadUrls": { "title": "Include download URLs", "type": "boolean", "description": "Keep download URLs when TikTok exposes them in the source payload.", "default": true }, "sessionCookieHeader": { "title": "Session cookie header", "type": "string", "description": "Optional raw Cookie header copied from a logged-in browser session. Helps when TikTok degrades public surfaces." }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional proxy configuration for region-sensitive or anti-bot-heavy targets." }, "emptyRunPolicy": { "title": "Empty run policy", "enum": [ "retry_then_fail", "retry_then_succeed", "retry_then_warn" ], "type": "string", "description": "How the actor should exit when targets were reachable but no videos were emitted after retry.", "default": "retry_then_warn" }, "debugMode": { "title": "Debug mode", "type": "boolean", "description": "Include extra runtime warnings for troubleshooting.", "default": 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 } } } } } } } } } } ```