# TikTok Playlist Scraper (`crawlerbros/tiktok-playlist-scraper`) Actor Scrape TikTok playlists - discover all playlists for a profile, get playlist metadata, and extract all videos. Supports playlist URLs, IDs, and profile URLs. No cookies required. - **URL**: https://apify.com/crawlerbros/tiktok-playlist-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Social media, Automation, Videos - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results 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 Playlist Scraper Scrape TikTok playlists (called "mixes" in the API) by providing playlist URLs, playlist IDs, profile URLs, or plain usernames. The actor discovers all playlists for a profile or targets specific playlists directly, then returns playlist metadata rows and video post rows with each video's position in the playlist. No login or cookies required. ### What this actor does - Accepts playlist URLs, raw playlist IDs, profile URLs, or usernames — any combination of these inputs - Discovers all playlists for a given profile and scrapes each one up to a configurable limit - Emits a metadata row per playlist with name, video count, creator info, cover thumbnail, and share metadata - Emits a post row for every video in each playlist, including the video's position within the playlist - Supports three modes: `metadata` (playlist info only), `posts` (videos only), and `both` - Empty fields are omitted ### Output per playlist metadata record - `rowType` — always `"playlist"` - `playlistId` — unique playlist/mix ID - `playlistName` — playlist name as set by the creator - `videoCount` — total number of videos in the playlist - `playlistUrl` — full URL to the playlist page - `creatorId` — creator's TikTok user ID - `creatorUsername` — creator handle - `creatorDisplayName` — creator display name - `creatorVerified` — whether the creator is verified - `coverPostId` — ID of the video used as the playlist cover - `coverThumbnailUrl` — thumbnail image URL of the cover video - `shareMeta.title` — share title text - `shareMeta.desc` — share description text - `scrapedAt` — ISO 8601 timestamp of when the record was collected ### Output per post record - `rowType` — always `"post"` - `playlistId` — ID of the playlist this post belongs to - `playlistName` — name of the playlist - `positionInPlaylist` — zero-based position of this video within the playlist - `postId` — unique TikTok video ID - `postUrl` — direct URL to the video - `caption` — full caption text - `likeCount` — total likes - `commentCount` — total comments - `shareCount` — total shares - `playCount` — total plays/views - `author.id` — author's TikTok user ID - `author.username` — author handle - `author.displayName` — author display name - `author.verified` — verification status - `author.avatarUrl` — author profile image URL - `music.id` — sound ID - `music.title` — sound title - `music.authorName` — sound creator name - `video.width` — video width in pixels - `video.height` — video height in pixels - `video.duration` — video duration in seconds - `video.playUrl` — streamable video URL (expires) - `video.cover` — cover/thumbnail image URL - `hashtags` — array of hashtag names parsed from caption - `scrapedAt` — ISO 8601 timestamp of when the record was collected ### Input | Field | Type | Default | Description | |---|---|---|---| | `playlistUrls` | string[] | — | Full TikTok playlist URLs. Example: `https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178` | | `playlistIds` | string[] | — | Raw numeric playlist/mix IDs (15–20 digits). | | `profileUrls` | string[] | — | Profile URLs — all playlists for each user will be discovered and scraped. | | `usernames` | string[] | — | TikTok usernames (with or without `@`) — all playlists will be discovered and scraped. | | `mode` | string | `"both"` | `"both"` returns metadata + posts. `"metadata"` returns playlist info only. `"posts"` returns videos only. | | `maxPostsPerPlaylist` | integer | 100 | Maximum videos to fetch per playlist (1–5000). | | `maxPlaylistsPerProfile` | integer | 20 | Maximum playlists to scrape per profile when discovering from a username or profile URL (1–100). | #### Example: discover playlists by username (metadata only) ```json { "usernames": ["natgeo"], "mode": "metadata", "maxPlaylistsPerProfile": 5 } ```` #### Example: scrape a specific playlist by URL ```json { "playlistUrls": ["https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178"], "mode": "both", "maxPostsPerPlaylist": 50 } ``` #### Example: multiple profiles — full video archive ```json { "usernames": ["natgeo", "nasa"], "mode": "both", "maxPostsPerPlaylist": 500, "maxPlaylistsPerProfile": 20 } ``` #### Example: bare playlist IDs ```json { "playlistIds": ["7509464647364283178", "7501234567890123456"], "mode": "posts", "maxPostsPerPlaylist": 100 } ``` ### Use cases - **Content archivists** backing up all videos from a creator's curated playlists before content is deleted - **Media researchers** studying how creators organize their content into thematic series or collections - **Brand teams** auditing playlist-organized product review or tutorial content from influencers - **Talent managers** tracking playlist growth and video count over time to measure creator output - **Developers** building structured content libraries from TikTok playlist data for client apps - **E-learning platforms** collecting structured educational video series from knowledge-creator playlists ### FAQ **Q: Do I need login or cookies?**\ A: No. The actor works without any credentials. **Q: How many playlists can a creator have?**\ A: TikTok allows creators to have multiple playlists (called "mixes"). The `maxPlaylistsPerProfile` setting controls how many are scraped per profile. **Q: What is `mode: "metadata"` useful for?**\ A: It fetches only playlist names, video counts, and creator info without loading any videos. This is the fastest way to audit which playlists a creator has and how large they are. **Q: What does `positionInPlaylist` mean?**\ A: It is the zero-based index of the video within the playlist as returned by TikTok's API. Position 0 is the first video in the playlist. **Q: What if a playlist has no public videos?**\ A: Playlists with no accessible videos return only a metadata row (when mode includes metadata) with `videoCount: 0` and no post rows. **Q: Are video URLs permanent?**\ A: No. TikTok's video play and cover image URLs are signed and expire after several hours. Use `postUrl` as the stable reference. **Q: Can I mix different input types in one run?**\ A: Yes. You can combine `playlistUrls`, `playlistIds`, `profileUrls`, and `usernames` in a single run. All are processed together. **Q: How many videos can I get per playlist?**\ A: Up to 5,000 per playlist via the `maxPostsPerPlaylist` setting. ### Related TikTok Scrapers Build a complete TikTok data pipeline with our full suite: | Scraper | URL | |---|---| | TikTok Post Scraper | https://apify.com/crawlerbros/tiktok-post-scraper | | TikTok Profile Scraper | https://apify.com/crawlerbros/tiktok-profile-scraper | | TikTok Comments Scraper | https://apify.com/crawlerbros/tiktok-comments-scraper | | TikTok Search Scraper | https://apify.com/crawlerbros/tiktok-search-scraper | | TikTok Hashtag Scraper | https://apify.com/crawlerbros/tiktok-hashtag-scraper | | TikTok Music Scraper | https://apify.com/crawlerbros/tiktok-music-scraper | | TikTok Transcript Scraper | https://apify.com/crawlerbros/tiktok-transcript-scraper | | TikTok Followers Scraper | https://apify.com/crawlerbros/tiktok-followers-scraper | | TikTok Mention Scraper | https://apify.com/crawlerbros/tiktok-mention-scraper | | TikTok Profile Mention Scraper | https://apify.com/crawlerbros/tiktok-profile-mention-scraper | | TikTok Explore Scraper | https://apify.com/crawlerbros/tiktok-explore-scraper | | TikTok For You Scraper | https://apify.com/crawlerbros/tiktok-for-you-scraper | | TikTok Downloader | https://apify.com/crawlerbros/tiktok-downloader-api | | TikTok Ads Library Scraper | https://apify.com/crawlerbros/tiktok-ads-library-scraper-pro | | TikTok Top Ads Scraper | https://apify.com/crawlerbros/tiktok-top-ads-scraper | | TikTok Hashtag Trends Scraper | https://apify.com/crawlerbros/tiktok-hashtag-trends-scraper | | TikTok LIVE Scraper | https://apify.com/crawlerbros/tiktok-live-scraper | # Actor input Schema ## `playlistUrls` (type: `array`): TikTok playlist URLs to scrape. E.g. https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178 ## `playlistIds` (type: `array`): Numeric playlist/mix IDs as strings (15–20 digits). Use instead of or together with Playlist URLs. ## `profileUrls` (type: `array`): TikTok profile URLs. All playlists for each user will be discovered and scraped. ## `usernames` (type: `array`): TikTok usernames (with or without @). All playlists for each user will be discovered and scraped. ## `mode` (type: `string`): Choose what data to return: playlist metadata rows only, post/video rows only, or both together. ## `maxPostsPerPlaylist` (type: `integer`): Maximum number of videos to extract per playlist. Higher values take longer but return more complete results. ## `maxPlaylistsPerProfile` (type: `integer`): Maximum number of playlists to scrape when discovering playlists for a profile. ## Actor input object example ```json { "playlistUrls": [ "https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178" ], "usernames": [ "natgeo" ], "mode": "metadata", "maxPostsPerPlaylist": 100, "maxPlaylistsPerProfile": 5 } ``` # Actor output Schema ## `data` (type: `string`): Dataset containing playlist metadata and video post records. Playlist rows have rowType='playlist' with playlistId, playlistName, videoCount, creatorUsername, playlistUrl. Post rows have rowType='post' with postId, caption, likeCount, playCount, commentCount, shareCount, createdAt, author, music, video, positionInPlaylist. # 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 = { "playlistUrls": [ "https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178" ], "usernames": [ "natgeo" ], "mode": "metadata", "maxPostsPerPlaylist": 100, "maxPlaylistsPerProfile": 5 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/tiktok-playlist-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 = { "playlistUrls": ["https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178"], "usernames": ["natgeo"], "mode": "metadata", "maxPostsPerPlaylist": 100, "maxPlaylistsPerProfile": 5, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/tiktok-playlist-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 '{ "playlistUrls": [ "https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178" ], "usernames": [ "natgeo" ], "mode": "metadata", "maxPostsPerPlaylist": 100, "maxPlaylistsPerProfile": 5 }' | apify call crawlerbros/tiktok-playlist-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/tiktok-playlist-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "TikTok Playlist Scraper", "description": "Scrape TikTok playlists - discover all playlists for a profile, get playlist metadata, and extract all videos. Supports playlist URLs, IDs, and profile URLs. No cookies required.", "version": "1.0", "x-build-id": "EJl3fyehpe9H5RJl7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~tiktok-playlist-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-tiktok-playlist-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/crawlerbros~tiktok-playlist-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-tiktok-playlist-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/crawlerbros~tiktok-playlist-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-tiktok-playlist-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": { "playlistUrls": { "title": "Playlist URLs", "type": "array", "description": "TikTok playlist URLs to scrape. E.g. https://www.tiktok.com/@natgeo/playlist/Cinematic-7509464647364283178", "items": { "type": "string" } }, "playlistIds": { "title": "Playlist IDs (Mix IDs)", "type": "array", "description": "Numeric playlist/mix IDs as strings (15–20 digits). Use instead of or together with Playlist URLs.", "items": { "type": "string" } }, "profileUrls": { "title": "Profile URLs", "type": "array", "description": "TikTok profile URLs. All playlists for each user will be discovered and scraped.", "items": { "type": "string" } }, "usernames": { "title": "Usernames", "type": "array", "description": "TikTok usernames (with or without @). All playlists for each user will be discovered and scraped.", "items": { "type": "string" } }, "mode": { "title": "Scraping Mode", "enum": [ "metadata", "posts", "both" ], "type": "string", "description": "Choose what data to return: playlist metadata rows only, post/video rows only, or both together.", "default": "both" }, "maxPostsPerPlaylist": { "title": "Max Posts Per Playlist", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of videos to extract per playlist. Higher values take longer but return more complete results.", "default": 100 }, "maxPlaylistsPerProfile": { "title": "Max Playlists Per Profile", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of playlists to scrape when discovering playlists for a profile.", "default": 20 } } }, "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 } } } } } } } } } } ```