# TikTok πŸ”₯ Viral Atlas (`badruddeen/tiktok-viral-atlas`) Actor TikTok Viral Network Atlas maps TikTok content diffusion with related video discovery, metadata, engagement analytics, creator clustering, and a unique posting-time intelligence layer that reveals when and how virality spreads over time. Generates a beautiful network-style viral trend report. - **URL**: https://apify.com/badruddeen/tiktok-viral-atlas.md - **Developed by:** [Badruddeen Naseem](https://apify.com/badruddeen) (community) - **Categories:** Social media, Videos, AI - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $25.00 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 πŸ”₯ Viral Atlas ### What does TikTok πŸ”₯ Viral Atlas do? TikTok πŸ”₯ Viral Atlas enables you to gain deeper insights into TikTok content diffusion and virality patterns than the official TikTok API allows. TikTok πŸ”₯ Viral Atlas can extract: - Related video discovery and content clustering - Comprehensive video metadata (posting time, views, likes, shares, comments) - Creator information and clustering analysis - Real-time engagement analytics and trends - Posting-time intelligence revealing when content goes viral - Network-style viral trend visualization and reporting - Content diffusion patterns across the platform --- ### Demo Video **Watch the full actor in action with interactive HTML report:** https://youtu.be/PvB7_NYek_8 --- ### Input Provide the following JSON input: ```json { "profileUrl": "https://www.tiktok.com/@arayfer_ha/video/7632888578372013320", "maxVideosToDiscover": 15, "runFullPipeline": true, "testMode": false } ```` *** #### Input Fields | Field | Type | Required | Default | Description | |------------------------|-----------|----------|-------------|-----------| | `profileUrl` | string | βœ… | - | TikTok video URL to start crawling from. Must contain `/video/`. | | `maxVideosToDiscover` | integer | ❌ | `10` | Number of related videos to discover (minimum 2, maximum 50). | | `runFullPipeline` | boolean | ❌ | `false` | Set to `true` to scrape full metadata and generate the enhanced HTML report. | | `testMode` | boolean | ❌ | `false` | Enable quick test mode (only scrapes 1 video with minimal data). | --------------------------------------------------------------------------------------------------------------------------------- ### Output The actor produces a flat array of objects with the following structure: ```json [ { "seedVideoUrl": "https://www.tiktok.com/@username/video/1234567890123456789", "seedUsername": "username", "relatedVideoUrl": "https://www.tiktok.com/@creator/video/9876543210987654321", "relatedCreator": "creator", "relatedScrapedAt": "2026-06-05T13:53:00.000Z", "postedTimestampUTC": 1749120000000, "postedDateUTC": "2025-06-05", "postedTimeUTC": "12:00:00", "sequenceNumber": 123456, "machineId": null, "authorHandle": "@creator", "authorName": "Creator Name", "description": "This is an example video description πŸ”₯", "hashtags": ["#trending", "#viral", "#fyp"], "views": "2450000", "likes": "124500", "comments": "3240", "shares": "8750", "bookmarks": "12400", "music": "Original Sound - Creator Name", "pageTitle": "TikTok | Example Video Title", "scrapedAt": "2026-06-05T13:53:22.147Z" } ] ``` *** ### Results The actor returns structured JSON data including: ```json { "videoId": "7123456789012345678", "description": "Amazing viral moment πŸ”₯", "views": 2500000, "likes": 125000, "shares": 45000, "comments": 12000, "creatorId": "user123", "creatorUsername": "@creator_name", "postTime": "2024-01-15T14:30:00Z", "viralScore": 0.92, "relatedVideos": ["id1", "id2", "id3"], "engagementRate": 0.068, "diffusionPattern": "exponential" } ``` *** ### HTML Report Visualization When `runFullPipeline` is enabled, the actor creates a professional interactive HTML visualization: - Interactive **network graph** showing seed video β†’ related videos - Hover tooltips with rich metadata - Full sortable data table - Clean and shareable report ## This makes it very easy to analyze TikTok content clusters visually. ### How It Works - Crawl Related Videos - The crawler navigates to the provided TikTok video URL using PlaywrightCrawler. - Extracts links to related videos from TikTok’s discovery feed. - Ensures unique creators and avoids duplicates. ### Fetch Metadata Retrieves posting time, likes, comments, shares, bookmarks, views, hashtags, music, and more. Flatten Results Combines the related video info and metadata into a single output array. *** ### Configuration Tips Concurrency: maxConcurrency: 3 – up to 3 pages can be scraped in parallel. Adjust carefully to avoid TikTok rate limits. Session Pool: Sessions last up to 3600 seconds. Avoid persistState to reduce session conflicts and blocks. Retries & Timeout: Each request retries up to 5 times (maxRequestRetries: 5) and allows 300 seconds (requestHandlerTimeoutSecs: 300) to handle slow responses. *** ### Installation & Running Locally ``` git clone cd tiktok-video-discovery-engine npm install ``` #### Run locally with: ``` APIFY_TOKEN= node src/main.js ``` \*\* Or deploy as an Apify actor and provide input via the web interface. \*\* *** ### Why scrape TikTok? With over 1 billion active users, TikTok is one of the world's most influential social media platforms and an invaluable source of data for understanding viral content dynamics and audience behavior. Here are just some of the ways you could use TikTok data: - Identify trending topics and viral patterns to stay ahead of market trends - Analyze creator strategies and posting times to optimize your own content - Monitor brand mentions and competitor performance in real-time - Understand audience engagement patterns and virality mechanics - Discover emerging creators and niche communities in your industry - Build data-driven content calendars based on viral intelligence - Conduct market research and consumer behavior analysis If you would like more inspiration on how scraping TikTok could help your business or organization, check out our [industry pages](https://apify.com/industries). ### How to scrape TikTok It's easy to scrape TikTok with TikTok πŸ”₯ Viral Atlas. Just follow these few steps and you'll get your data in minutes. 1. Click on **Try for free**. 2. Enter the Starting TikTok Video URL. 3. Enable Run Full Pipeline (Fetch Statistics) 4. Select the Maximum Videos to Discover - Click on **Run - Start**. 5. When TikTok πŸ”₯ Viral Atlas has finished, preview or download your data from the Dataset tab. ### How much will it cost to scrape TikTok? Apify gives you $5 free usage credits every month on the [Apify Free plan](https://apify.com/pricing). You can scrape a substantial amount of TikTok data with that allocation, so your initial analysis will be completely free! If you need to gather data regularly from TikTok, we recommend our [$49/month Starter plan](https://apify.com/pricing) - perfect for ongoing trend monitoring and content analysis. For large-scale research and enterprise needs, the [Scale plan](https://apify.com/pricing) at $499/month offers unlimited data collection and advanced analytics features. Please check actor pricing tab for pricing. ### Tips for scraping TikTok - Use specific hashtags and keywords to focus your viral trend analysis - Schedule regular scraping runs to track how virality evolves over time - Combine posting-time data with engagement metrics to identify optimal content timing - Analyze creator clusters to find influencers within your niche - Export network visualizations for presentations and stakeholder reports - Monitor competitor hashtags and creator accounts for competitive intelligence ### Is it legal to scrape TikTok? Note that personal data is protected by GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. #### In test mode, the actor runs in validation mode and does not scrape real TikTok data. We also recommend that you read our blog post: [is web scraping legal?](https://blog.apify.com/is-web-scraping-legal/) *** For more information and to get started, visit the [TikTok πŸ”₯ Viral Atlas actor page](https://apify.com/badruddeen/tiktok-viral-atlas). # Actor input Schema ## `profileUrl` (type: `string`): Paste any public TikTok video URL. The actor will discover related videos from TikTok's recommendation feed. ## `runFullPipeline` (type: `boolean`): When enabled, the actor will scrape detailed metadata (video posted time, views, likes, comments, shares, description, hashtags, music, etc.). This significantly increases runtime and compute usage. ## `maxVideosToDiscover` (type: `integer`): How many related videos to find. Higher numbers take longer. ## `testMode` (type: `boolean`): Fast test mode for development and validation. Limits discovery to 1 video and skips heavy operations. ## Actor input object example ```json { "profileUrl": "https://www.tiktok.com/@overtime/video/7576031263010737422", "runFullPipeline": false, "maxVideosToDiscover": 10, "testMode": false } ``` # Actor output Schema ## `overview` (type: `string`): No description ## `fullReport` (type: `string`): No description ## `lightReport` (type: `string`): No description ## `allFields` (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 = {}; // Run the Actor and wait for it to finish const run = await client.actor("badruddeen/tiktok-viral-atlas").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 = {} # Run the Actor and wait for it to finish run = client.actor("badruddeen/tiktok-viral-atlas").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 '{}' | apify call badruddeen/tiktok-viral-atlas --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=badruddeen/tiktok-viral-atlas", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok πŸ”₯ Viral Atlas", "description": "TikTok Viral Network Atlas maps TikTok content diffusion with related video discovery, metadata, engagement analytics, creator clustering, and a unique posting-time intelligence layer that reveals when and how virality spreads over time. Generates a beautiful network-style viral trend report.", "version": "0.0", "x-build-id": "FXKXr4vZSDfPv3MfM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/badruddeen~tiktok-viral-atlas/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-badruddeen-tiktok-viral-atlas", "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/badruddeen~tiktok-viral-atlas/runs": { "post": { "operationId": "runs-sync-badruddeen-tiktok-viral-atlas", "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/badruddeen~tiktok-viral-atlas/run-sync": { "post": { "operationId": "run-sync-badruddeen-tiktok-viral-atlas", "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": [ "profileUrl" ], "properties": { "profileUrl": { "title": "Starting TikTok Video URL", "pattern": "^https?://(www\\.)?tiktok\\.com/.*", "minLength": 20, "type": "string", "description": "Paste any public TikTok video URL. The actor will discover related videos from TikTok's recommendation feed.", "default": "https://www.tiktok.com/@overtime/video/7576031263010737422" }, "runFullPipeline": { "title": "πŸ”₯ Run Full Pipeline (Fetch Statistics)", "type": "boolean", "description": "When enabled, the actor will scrape detailed metadata (video posted time, views, likes, comments, shares, description, hashtags, music, etc.). This significantly increases runtime and compute usage.", "default": false }, "maxVideosToDiscover": { "title": "Maximum Videos to Discover", "minimum": 2, "maximum": 50, "type": "integer", "description": "How many related videos to find. Higher numbers take longer.", "default": 10 }, "testMode": { "title": "Test Mode (Internal)", "type": "boolean", "description": "Fast test mode for development and validation. Limits discovery to 1 video and skips heavy operations.", "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 } } } } } } } } } } ```