# TikTok Story Viewer (`maximedupre/tiktok-story-viewer`) Actor View and export active public TikTok stories from usernames or profile URLs. Get video links, covers, timestamps, engagement stats, music metadata, author details, and clean dataset exports. - **URL**: https://apify.com/maximedupre/tiktok-story-viewer.md - **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community) - **Categories:** Social media, Videos - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $4.50 / 1,000 stories 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 Story Viewer for active public stories TikTok Story Viewer exports currently active public stories from [TikTok](https://www.tiktok.com/) usernames, @handles, or profile URLs. Add profiles such as `hbomax`, `@tiktok`, or `https://www.tiktok.com/@jasonderulo`, then get one clean dataset row per active story with video links, cover images, timestamps, engagement stats, music metadata, author details, source identifiers, and scrape timestamps. Use this TikTok story viewer when you need a repeatable way to check public TikTok stories for brand monitoring, creator research, social media reporting, content review, or archiving workflows. The Actor is focused on public profile stories only. You do not need to provide TikTok cookies, a TikTok login, or a TikTok API key. For a useful first run, keep the prefilled profile set and default limits. TikTok stories are temporary, so a zero-row run usually means the submitted profiles have no active public stories at that moment. ### ✅ What this Actor does - Accepts TikTok usernames, @handles, and public profile URLs. - Checks active public stories for each submitted profile. - Saves one dataset row per active story. - Adds video URLs, watermarked video URLs when available, cover images, and duration. - Adds story IDs, video IDs, source profile URLs, story URLs when they can be built, and scrape timestamps. - Adds visible engagement stats such as views, likes, comments, shares, downloads, and collects when TikTok exposes them. - Adds music metadata such as sound title, author, audio URL, cover URL, duration, and original-sound flag when available. - Adds author details such as TikTok user ID, username, display name, and avatar URL. - Skips profiles that are private, unavailable, unsupported, or without active public stories without saving placeholder rows. This Actor does not discover profiles, scrape regular TikTok videos, scrape comments, search TikTok, monitor hashtags, collect followers, or download binary files into storage. It returns the public story data and media URLs TikTok exposes during the run. ### 📦 Data you can export Each output row represents one active TikTok story. Core fields include: - `inputIndex` and `input` - `profileUsername` and `profileUrl` - `authorId`, `authorUsername`, `authorName`, and `authorAvatarUrl` - `storyId`, `videoId`, and `storyUrl` - `createdAt`, `createdTimestamp`, `durationSeconds`, and `region` - `videoUrl`, `watermarkedVideoUrl`, `coverUrl`, `dynamicCoverUrl`, and `originCoverUrl` - `playCount`, `likeCount`, `commentCount`, `shareCount`, `downloadCount`, and `collectCount` - `musicId`, `musicTitle`, `musicAuthor`, `musicUrl`, `musicCoverUrl`, `musicDurationSeconds`, and `isOriginalSound` - `engagement`, `music`, `media`, and `commerce` objects for structured workflows - `scrapedAt` You can open the dataset in Apify, export it as JSON, CSV, Excel, XML, RSS, or HTML, call it through the Apify API, schedule repeat checks, or send rows to webhooks and integrations. ### 🚀 How to run 1. Add one or more TikTok profiles in **TikTok profiles**. 2. Use usernames such as `hbomax`, @handles such as `@tiktok`, or full profile URLs such as `https://www.tiktok.com/@jasonderulo`. 3. Keep **Profile limit** small for a first run, or raise it for a larger batch. 4. Leave **Story limit per profile** at `0` to save all currently active stories, or set a number to cap each profile. 5. Choose **Story order** if you need newest-first, oldest-first, or TikTok's profile order. 6. Start the Actor and open the dataset. Stories expire quickly. If a profile has no active public story when the Actor checks it, no row is saved for that profile. ### 🔧 Input | Field | What to enter | | ----- | ------------- | | `targets` | TikTok usernames, @handles, or public profile URLs. | | `maxProfiles` | Maximum number of profiles to check from your target list. Default is `19`. | | `maxStoriesPerProfile` | Maximum active stories to save for each profile. `0` means all active stories found. | | `sortStories` | Output order for stories from each profile: `newest`, `oldest`, or `profileOrder`. | Example input: ```json { "targets": ["hbomax", "@tiktok", "https://www.tiktok.com/@jasonderulo"], "maxProfiles": 3, "maxStoriesPerProfile": 0, "sortStories": "newest" } ```` ### 📄 Output example ```json { "inputIndex": 1, "input": "hbomax", "profileUsername": "hbomax", "profileUrl": "https://www.tiktok.com/@hbomax", "authorId": "6803724582765200389", "authorUsername": "hbomax", "authorName": "HBO Max", "storyId": "7645112817745480991", "videoId": "7645112817745480991", "storyUrl": "https://www.tiktok.com/@hbomax/video/7645112817745480991", "createdAt": "2026-05-29T01:02:27.000Z", "durationSeconds": 14, "videoUrl": "https://v16-webapp-prime.us.tiktok.com/...", "coverUrl": "https://p16-common-sign.tiktokcdn-us.com/...", "playCount": 12302, "likeCount": 467, "commentCount": 0, "shareCount": 7, "musicTitle": "original sound - Game of Thrones", "musicAuthor": "Game of Thrones", "isOriginalSound": true, "scrapedAt": "2026-05-29T19:53:01.726Z" } ``` Some fields can be `null` when TikTok does not expose that value for a story. ### 💸 Pricing This Actor uses pay-per-event pricing. You are charged for each active TikTok story saved to the dataset. Profiles with no active public stories do not create dataset rows. The local pricing artifact sets the primary **Story** charge at `$0.018` on the FREE tier and `$0.0045` on BRONZE, SILVER, GOLD, PLATINUM, and DIAMOND tiers. The live Pricing tab is the source of truth once the Actor is published. ### ⚠️ Limits and caveats - TikTok stories are temporary and can disappear between runs. - Media URLs may expire, so save important media soon after export. - Private, deleted, unavailable, or restricted profiles are skipped. - The Actor works with public profile stories, not regular profile videos or TikTok search. - Output depends on what TikTok exposes publicly at run time. ### ❓ FAQ #### 🔐 Do I need TikTok cookies or a login? No. The Actor is designed for public TikTok story data and does not ask you for cookies, login credentials, or an API key. #### 🔎 Why did my run return zero rows? Most often, the submitted profiles had no active public stories when the Actor checked them. TikTok stories are temporary, so try another public profile or run again later. #### 📥 Does this download the video files? No. It exports TikTok media URLs and metadata. If you need saved media files from regular TikTok video URLs, use TikTok Video Downloader. #### 🕒 Can I run this on a schedule? Yes. You can schedule the Actor on Apify to check the same profiles repeatedly and export each run's dataset through the API, webhooks, or integrations. ### 📝 Changelog - 0.1: Initial release with active public story exports, structured story metadata, and a useful default profile set. - 0.0: Initial release. ### 🆘 Support For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~tiktok-story-viewer/issues) and I'll fix or implement it in less than 24h 🫡 ### 🔗 Other actors - [TikTok Video Downloader ↗](https://apify.com/maximedupre/tiktok-video-downloader) - download media files from known public TikTok video URLs. - [TikTok Transcript Scraper ↗](https://apify.com/maximedupre/tiktok-transcript-scraper) - extract transcripts, captions, subtitles, and metadata from public TikTok videos. - [TikTok Keywords Discovery Tool ↗](https://apify.com/maximedupre/tiktok-keywords-discovery-tool) - collect TikTok autocomplete keyword suggestions for content planning. - [Instagram Downloader API ↗](https://apify.com/maximedupre/instagram-downloader-api) - export direct media links from public Instagram posts and reels. - [YouTube Channel Scraper ↗](https://apify.com/maximedupre/youtube-channel-scraper) - export public YouTube channel profiles and recent video rows. **Made with ❤️ by Maxime Dupré** # Actor input Schema ## `targets` (type: `array`): Enter TikTok usernames such as `hbomax`, @handles such as `@tiktok`, or public profile URLs. Video, search, hashtag, comment, and private profile URLs are not supported. ## `maxProfiles` (type: `integer`): Maximum number of profiles to check from the target list. Keep this low for a small first run. ## `maxStoriesPerProfile` (type: `integer`): Maximum active stories to save for each profile. Use `0` to save every active story TikTok currently exposes for each profile. ## `sortStories` (type: `string`): Choose the order used when saving active stories from each profile. ## Actor input object example ```json { "targets": [ "accuweather", "airbnb", "dailymail", "elfyeah", "enews", "fifaworldcup", "guardian", "hbo", "hbomax", "jamescharles", "netflixfr", "nhl", "olivertree", "panerabread", "pepsi", "qatarairways", "summerfridays", "tiktok", "wnba" ], "maxProfiles": 19, "maxStoriesPerProfile": 0, "sortStories": "newest" } ``` # Actor output Schema ## `results` (type: `string`): Open the dataset with active TikTok stories, source links, media URLs, music, engagement, and author fields. # 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 = { "targets": [ "accuweather", "airbnb", "dailymail", "elfyeah", "enews", "fifaworldcup", "guardian", "hbo", "hbomax", "jamescharles", "netflixfr", "nhl", "olivertree", "panerabread", "pepsi", "qatarairways", "summerfridays", "tiktok", "wnba" ] }; // Run the Actor and wait for it to finish const run = await client.actor("maximedupre/tiktok-story-viewer").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 = { "targets": [ "accuweather", "airbnb", "dailymail", "elfyeah", "enews", "fifaworldcup", "guardian", "hbo", "hbomax", "jamescharles", "netflixfr", "nhl", "olivertree", "panerabread", "pepsi", "qatarairways", "summerfridays", "tiktok", "wnba", ] } # Run the Actor and wait for it to finish run = client.actor("maximedupre/tiktok-story-viewer").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 '{ "targets": [ "accuweather", "airbnb", "dailymail", "elfyeah", "enews", "fifaworldcup", "guardian", "hbo", "hbomax", "jamescharles", "netflixfr", "nhl", "olivertree", "panerabread", "pepsi", "qatarairways", "summerfridays", "tiktok", "wnba" ] }' | apify call maximedupre/tiktok-story-viewer --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=maximedupre/tiktok-story-viewer", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Story Viewer", "description": "View and export active public TikTok stories from usernames or profile URLs. Get video links, covers, timestamps, engagement stats, music metadata, author details, and clean dataset exports.", "version": "0.1", "x-build-id": "Qpd55IKBj2AghvxMN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/maximedupre~tiktok-story-viewer/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-maximedupre-tiktok-story-viewer", "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/maximedupre~tiktok-story-viewer/runs": { "post": { "operationId": "runs-sync-maximedupre-tiktok-story-viewer", "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/maximedupre~tiktok-story-viewer/run-sync": { "post": { "operationId": "run-sync-maximedupre-tiktok-story-viewer", "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": [ "targets" ], "properties": { "targets": { "title": "TikTok profiles", "minItems": 1, "maxItems": 500, "uniqueItems": true, "type": "array", "description": "Enter TikTok usernames such as `hbomax`, @handles such as `@tiktok`, or public profile URLs. Video, search, hashtag, comment, and private profile URLs are not supported.", "items": { "type": "string" } }, "maxProfiles": { "title": "Profile limit", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of profiles to check from the target list. Keep this low for a small first run.", "default": 19 }, "maxStoriesPerProfile": { "title": "Story limit per profile", "minimum": 0, "maximum": 100, "type": "integer", "description": "Maximum active stories to save for each profile. Use `0` to save every active story TikTok currently exposes for each profile.", "default": 0 }, "sortStories": { "title": "Story order", "enum": [ "newest", "oldest", "profileOrder" ], "type": "string", "description": "Choose the order used when saving active stories from each profile.", "default": "newest" } } }, "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 } } } } } } } } } } ```