# TikTok Story Viewer Scraper (`automation-lab/tiktok-story-viewer-scraper`) Actor 🎬 Check public TikTok profiles for story availability, story status codes, and profile metadata without login. - **URL**: https://apify.com/automation-lab/tiktok-story-viewer-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event + usage This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 Story Viewer Scraper Track public TikTok profile story availability and export story-status metadata at scale. ### What does TikTok Story Viewer Scraper do? TikTok Story Viewer Scraper checks public TikTok profiles and returns profile story availability, account metadata, and diagnostic story fields from TikTok's public profile HTML. Use it when you need to know whether a brand, creator, competitor, or campaign account currently exposes story-related signals without manually opening each profile. The actor is built for public data. It does not require TikTok login cookies, passwords, or private API keys. ### Who is it for? - 📣 Social media managers monitoring creator activity - 🧑‍💼 Influencer agencies checking campaign participants - 🕵️ Brand-monitoring teams watching competitor accounts - 📊 Analysts combining TikTok profile data with content calendars - 🤖 Automation teams that need repeatable story-status checks ### Why use this actor? TikTok Stories are temporary. Manual checks are slow, inconsistent, and hard to audit. This actor turns a list of TikTok profile URLs or usernames into structured rows that can be exported to JSON, CSV, Excel, Google Sheets, Make, Zapier, or your own API workflow. ### How the scraper works The actor fetches each public TikTok profile page and reads the embedded `__UNIVERSAL_DATA_FOR_REHYDRATION__` payload. It extracts profile metadata and story-related status fields such as `UserStoryStatus` when TikTok exposes them in the public HTML. ### Data you can extract | Field | Description | | --- | --- | | `profileUrl` | Normalized TikTok profile URL | | `username` | TikTok username | | `nickname` | Display name | | `verified` | Whether TikTok marks the account verified | | `privateAccount` | Whether the profile is private | | `followerCount` | Public follower count | | `storyStatus` | Raw TikTok story status code when available | | `hasActiveStory` | Normalized active-story indicator when determinable | | `storyStatusLabel` | Human-readable story status label | | `storyItemCount` | Number of story items found in embedded data | | `storyIds` | Story item IDs when embedded | | `storyUrls` | Story media URLs when embedded | | `scrapedAt` | ISO timestamp for the check | ### How much does it cost to scrape TikTok story status? The actor uses pay-per-event pricing with a small run-start event and one result event per saved profile row. A small monitoring run with 10 profiles is designed to be inexpensive. Larger recurring checks scale with the number of profile rows saved. ### Input You can provide either full TikTok profile URLs or usernames. Example input: ```json { "profileUrls": [ { "url": "https://www.tiktok.com/@tiktok" }, { "url": "https://www.tiktok.com/@tiktokforbusiness" } ], "usernames": ["tiktok"], "maxProfiles": 10, "includeRawData": false } ```` ### Output Example output row: ```json { "profileUrl": "https://www.tiktok.com/@tiktok", "username": "tiktok", "nickname": "TikTok", "verified": true, "followerCount": 94465285, "storyStatus": 0, "hasActiveStory": false, "storyStatusLabel": "no_active_story", "storyItemCount": 0, "storyIds": [], "storyUrls": [], "scrapedAt": "2026-06-19T00:00:00.000Z" } ``` ### Step-by-step usage 1. Open the actor on Apify. 2. Add TikTok profile URLs or usernames. 3. Keep `maxProfiles` low for your first test. 4. Run the actor. 5. Export the dataset or connect it to an integration. ### Tips for best results - Use profile URLs when you already have them. - Use usernames when your source system stores handles. - Schedule repeated runs for ephemeral story monitoring. - Keep raw diagnostics disabled unless you are debugging. - Expect some profiles to have no active public story at check time. ### Integrations Send results to Google Sheets for campaign monitoring. Trigger Make scenarios when `hasActiveStory` changes. Use Zapier to notify account managers about creator story activity. Pull dataset items through the Apify API for BI dashboards. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/tiktok-story-viewer-scraper').call({ usernames: ['tiktok'], maxProfiles: 5 }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/tiktok-story-viewer-scraper').call({ 'usernames': ['tiktok'], 'maxProfiles': 5, }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~tiktok-story-viewer-scraper/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"usernames":["tiktok"],"maxProfiles":5}' ``` ### MCP usage Use the actor from Claude through Apify MCP: `https://mcp.apify.com/?tools=automation-lab/tiktok-story-viewer-scraper` Claude Code setup: ```bash claude mcp add apify-tiktok-story-viewer https://mcp.apify.com/?tools=automation-lab/tiktok-story-viewer-scraper ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-tiktok-story-viewer": { "url": "https://mcp.apify.com/?tools=automation-lab/tiktok-story-viewer-scraper" } } } ``` Example prompts: - "Check these TikTok profiles for public story status." - "Create a table of TikTok accounts with active story signals." - "Monitor these creator handles and summarize story availability." ### Scheduling workflow Stories are temporary, so a scheduled run is often more useful than a one-time run. Run the actor hourly or daily, then compare the newest dataset with previous runs in your own database or spreadsheet. ### Troubleshooting If a profile returns an error, confirm that the profile URL is public and accessible in a browser. If `hasActiveStory` is `null`, TikTok did not expose enough public story data to make a definitive active/inactive decision. If `storyItemCount` is zero, the profile may simply have no active public story at the time of the run. ### Limitations TikTok may change public HTML fields at any time. The actor does not log in to TikTok. The actor does not bypass private accounts. Story media URLs are only returned when TikTok embeds them in the public profile payload. ### Legality and responsible use This actor extracts publicly available profile information. Use it responsibly, respect TikTok's terms, follow privacy rules, and avoid collecting data you are not allowed to process. ### Related TikTok scrapers - [TikTok Scraper](https://apify.com/automation-lab/tiktok-scraper) - [TikTok Profile Scraper](https://apify.com/automation-lab/tiktok-profile-scraper) - [TikTok Comments Scraper](https://apify.com/automation-lab/tiktok-comments-scraper) ### FAQ #### Does this download TikTok stories? It records story-status metadata and story media URLs only when they are exposed in public profile HTML. It is not a login-based downloader. #### Do I need cookies? No. The MVP is designed for public profile checks without cookies. #### Can I monitor many profiles? Yes. Add profile URLs or usernames and increase `maxProfiles` as needed. #### Why do some rows say no active story? Stories expire quickly, and many public profiles do not have an active story at the exact time of scraping. ### Changelog - Initial version: public TikTok profile story-status extraction. # Actor input Schema ## `profileUrls` (type: `array`): TikTok profile URLs to check for public story status, for example https://www.tiktok.com/@tiktok. ## `usernames` (type: `array`): TikTok usernames with or without @. Use this when you do not have full profile URLs. ## `maxProfiles` (type: `integer`): Safety cap for the number of unique profiles processed in one run. ## `includeRawData` (type: `boolean`): Adds compact raw fields whose keys mention story. Useful for debugging active-story profiles; leave off for normal exports. ## Actor input object example ```json { "profileUrls": [ { "url": "https://www.tiktok.com/@tiktok" }, { "url": "https://www.tiktok.com/@tiktokforbusiness" } ], "usernames": [ "tiktok" ], "maxProfiles": 10, "includeRawData": false } ``` # Actor output Schema ## `overview` (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 = { "profileUrls": [ { "url": "https://www.tiktok.com/@tiktok" }, { "url": "https://www.tiktok.com/@tiktokforbusiness" } ], "usernames": [ "tiktok" ] }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/tiktok-story-viewer-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 = { "profileUrls": [ { "url": "https://www.tiktok.com/@tiktok" }, { "url": "https://www.tiktok.com/@tiktokforbusiness" }, ], "usernames": ["tiktok"], } # Run the Actor and wait for it to finish run = client.actor("automation-lab/tiktok-story-viewer-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 '{ "profileUrls": [ { "url": "https://www.tiktok.com/@tiktok" }, { "url": "https://www.tiktok.com/@tiktokforbusiness" } ], "usernames": [ "tiktok" ] }' | apify call automation-lab/tiktok-story-viewer-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/tiktok-story-viewer-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Story Viewer Scraper", "description": "🎬 Check public TikTok profiles for story availability, story status codes, and profile metadata without login.", "version": "0.1", "x-build-id": "D0S5xBxuTdbXDce1u" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~tiktok-story-viewer-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-tiktok-story-viewer-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/automation-lab~tiktok-story-viewer-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-tiktok-story-viewer-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/automation-lab~tiktok-story-viewer-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-tiktok-story-viewer-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": { "profileUrls": { "title": "Profile URLs", "type": "array", "description": "TikTok profile URLs to check for public story status, for example https://www.tiktok.com/@tiktok.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "usernames": { "title": "Usernames", "type": "array", "description": "TikTok usernames with or without @. Use this when you do not have full profile URLs.", "items": { "type": "string" } }, "maxProfiles": { "title": "Maximum profiles", "minimum": 1, "maximum": 500, "type": "integer", "description": "Safety cap for the number of unique profiles processed in one run.", "default": 10 }, "includeRawData": { "title": "Include raw story diagnostics", "type": "boolean", "description": "Adds compact raw fields whose keys mention story. Useful for debugging active-story profiles; leave off for normal exports.", "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 } } } } } } } } } } ```