# Douyin Scraper — TikTok China API & Video Downloader (`sian.agency/douyin-scraper`) Actor Douyin scraper for TikTok China — extract video data, user profiles, comments, reply threads, and keyword search. KOL discovery, view counts, engagement metrics, China market research. Seven operations, one clean dataset per run. No API key. - **URL**: https://apify.com/sian.agency/douyin-scraper.md - **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community) - **Categories:** Social media, Videos, Automation - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 user videos 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 ## Douyin Scraper — TikTok China Videos, KOL Data, Comments & Search 🎥 [![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Taobao & Tmall](https://img.shields.io/badge/SI%C3%81N-Taobao%20%26%20Tmall-FF4F00)](https://apify.com/sian.agency/taobao-tmall-product-scraper?fpr=sian) [![Kwai & Kuaishou](https://img.shields.io/badge/SI%C3%81N-Kwai%20%26%20Kuaishou-FF4906)](https://apify.com/sian.agency/kwai-kuaishou-scraper?fpr=sian) [![TikTok Transcripts](https://img.shields.io/badge/SI%C3%81N-TikTok%20Transcripts-25F4EE)](https://apify.com/sian.agency/best-tiktok-ai-transcript-extractor?fpr=sian) #### 🎉 Seven scrapers in one — extract video data, profiles, comments, reply threads, user posts & keyword search from Douyin (TikTok China) ##### Built for KOL agencies, China-market researchers, brand teams, and content strategists who need clean structured Douyin data — no API key, no setup, no scraping headaches --- ### 📋 Overview **Tired of brittle DIY scrapers that break every time Douyin ships a UI tweak?** This actor delivers reliable, flat structured datasets from China's #1 short-video platform (700M+ DAU) — one clean run per task, one tidy dataset out. **Why teams choose SIÁN for Douyin data:** - ✅ **Seven operations, one actor**: video detail · user profile · user video catalog · comments · **sub-comments (reply threads)** · search videos · search users - 🧵 **Reply-thread depth no competitor offers** — pull the full conversation tree under any comment, not just top-level - 🔍 **Full-text search built in** — both `searchVideo` and `searchUser` work with Chinese, English, and mixed queries - ⚡ **10–20 results per page** on search & user feeds — paginate to 50 pages in a single run - 🎯 **Production-ready data shape**: curated camelCase aliases (videoId, secUid, userName, playCount, likeCount, caption, postedAt, …) PLUS the raw upstream fields for power users - 💰 **Pay-per-result pricing** — only charged for successful extractions, never for empty pages or errors - 💎 **No API key, no setup, no proxies** — paste a video ID, sec UID, or keyword and run - ✨ **19-digit Douyin aweme/uid/cid preserved at full precision** (most scrapers silently corrupt them); HTTPS auto-normalized on every media URL --- ### ✨ Features - 🎥 **Video Detail**: caption, play/like/share/comment/collect counts, playable video URL, cover, music, creator info, duration, timestamps - 👤 **User Profile**: follower count, following count, total likes received, post count, bio, verification badge, IP location, full avatar set - 📹 **User Videos**: full creator video catalog with engagement metrics, paginated ~20 videos/page - 💬 **Video Comments**: top-level comments with author, IP location, like count, reply count, hot-comment flag - 🧵 **Video Sub-Comments**: paginated reply threads under any comment — **unique to this actor** (no Douyin competitor exposes nested replies) - 🔍 **Search Videos**: keyword search supporting Chinese, English, and mixed queries — ~12 results/page - 🔎 **Search Users**: discover creators by keyword with handle, followers, verification, bio — ~19 results/page - 🖼️ **HTTPS-normalized URLs**: every video URL, cover, avatar, and music track ready to embed - 🆔 **BigInt-safe IDs**: 19-digit Douyin aweme/uid/cid preserved (no precision loss → no broken cross-operation joins) - 📄 **Cursor pagination**: stream through up to 50 pages per run with one input parameter - 📊 **HTML run report**: saved automatically to key-value store with success rate, errors, duration, inputs --- ### 🎬 Quick Start Paste a keyword to search Douyin trending videos — no Douyin API or downloader software required. ```bash curl -X POST https://api.apify.com/v2/acts/sian.agency~douyin-scraper/runs?token=YOUR_TOKEN \ -d '{"operation":"searchVideo","keyword":"美食","maxPages":3}' ```` *** ### 🚀 Getting Started (3 Simple Steps) #### Step 1: Pick an operation Choose what you want to extract: Search Videos, Search Users, Video Detail, User Profile, User Videos, Video Comments, or Video Sub-Comments. #### Step 2: Enter the input A keyword (search), a video ID (detail/comments/sub-comments), a sec UID (profile/videos), or a comment ID (sub-comments). #### Step 3: Click "Start" Results stream into the Apify dataset as they come back. Download as JSON, CSV, or Excel directly from the Console. **That's it! In under 60 seconds, you'll have:** - A flat, structured dataset (no nested CDN JSON to parse) - Curated camelCase fields plus the raw response for power users - An HTML report summarizing the run - Ready-to-embed HTTPS media URLs (videos, covers, avatars, music) *** ### 📥 Input Configuration | Field | Type | Required | Description | |-------|------|----------|-------------| | `operation` | string (enum) | Yes | One of: `videoDetail` · `userDetail` · `userVideos` · `videoComments` · `videoSubComments` · `searchVideo` · `searchUser` | | `videoId` | string | If operation is `videoDetail`, `videoComments`, or `videoSubComments` | Douyin numeric video ID (also called `aweme_id`). Find it in any Douyin video URL after `/video/`. | | `commentId` | string | If operation is `videoSubComments` | Numeric comment ID (`cid`). Find it in the `commentId` field of any `Video Comments` result row. | | `secUid` | string | If operation is `userDetail` or `userVideos` | Encrypted user handle starting with `MS4wLjAB...`. Find it in any profile URL after `/user/` or in any result row's `secUid` field. | | `keyword` | string | If operation is `searchVideo` or `searchUser` | Search query (Chinese, English, or mixed — e.g. `美食`, `dance`, `fashion`) | | `maxPages` | integer | No | Pages to fetch for paginated operations (default 5, max 50) | **Example — Search trending Douyin videos:** ```json { "operation": "searchVideo", "keyword": "美食", "maxPages": 3 } ``` **Example — Pull a creator's full video catalog:** ```json { "operation": "userVideos", "secUid": "MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "maxPages": 10 } ``` **Example — Get full video details by ID:** ```json { "operation": "videoDetail", "videoId": "7615930241370348219" } ``` **Example — Pull reply thread for a specific comment:** ```json { "operation": "videoSubComments", "videoId": "7615930241370348219", "commentId": "7615932448664650533", "maxPages": 5 } ``` *** ### 📤 Output Results are saved to the Apify dataset with **40+ curated fields** plus all raw upstream fields. Filter by `_operation` to split modes; two predefined dataset views ready to open in Apify Console (Overview / Comments). | Field | Type | Description | |-------|------|-------------| | `videoId` / `awemeId` | string | Douyin video ID (19-digit, precision preserved) | | `videoPageUrl` | string | Direct link to the video on Douyin | | `caption` | string | Video caption (Chinese / English / mixed, with hashtags & mentions) | | `videoUrl` | string | Playable video stream URL | | `videoUrlList` | array | All quality variants of the stream | | `coverUrl` | string | Primary video thumbnail | | `dynamicCoverUrls` | array | Animated cover (loop preview) | | `durationMs` | integer | Video length in milliseconds | | `playCount` | integer | Total plays | | `likeCount` | integer | Likes (digg\_count) | | `shareCount` | integer | Shares | | `commentCount` | integer | Comments | | `collectCount` | integer | Saves/bookmarks | | `postedAt` | string | ISO-8601 timestamp | | `musicId` / `musicTitle` / `musicAuthor` / `musicPlayUrl` | mixed | Background music metadata | | `userId` | string | Creator's numeric UID | | `secUid` | string | Creator's encrypted handle (use this for User Profile / User Videos) | | `uniqueId` | string | Creator's public @handle | | `userName` | string | Creator's display nickname | | `userVerified` | boolean | Verification badge | | `verifyReason` | string | Custom verification reason (e.g. enterprise/celebrity status) | | `userPageUrl` | string | Direct link to the creator's profile | | `avatarUrl` | string | Profile picture (HTTPS) | | `followerCount` / `followingCount` / `totalFavorited` / `awemeCount` | integer | Profile stats | | `userBio` | string | Profile signature/bio | | `ipLocation` / `userCity` / `userProvince` / `userCountry` | string | Geo metadata | | `commentId` | string | Comment ID (use as input to `Video Sub-Comments`) | | `parentCommentId` | string | For sub-comments: the parent comment | | `content` | string | Comment text | | `replyCount` | integer | Number of replies under this comment | | `isHot` | boolean | Pinned/stickied comment | | `isAuthorDigged` | boolean | Liked by the video creator | **Example dataset row (search video):** ```json { "_operation": "searchVideo", "_sourceKeyword": "美食", "videoId": "7615930241370348219", "userId": "58743577344", "secUid": "MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "userName": "章章干嘛呢", "uniqueId": "...", "caption": "夜宵简单吃个长沙滋啦冒油的炭烤牛肋排和三文鱼牛肉卷… #饭搭子 #深夜放毒 #寻味烟火气", "playCount": 0, "likeCount": 126484, "shareCount": 521446, "commentCount": 9883, "collectCount": 12144, "videoUrl": "https://...", "coverUrl": "https://...", "videoPageUrl": "https://www.douyin.com/video/7615930241370348219", "userPageUrl": "https://www.douyin.com/user/MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "postedAt": "2026-04-..", "status": "success" } ``` *** ### 💼 Use Cases & Examples #### 1. KOL & Creator Discovery for China-Market Brands **Influencer marketing teams** at Western brands shortlisting Douyin KOLs for product seeding and brand partnerships. **Input:** Search Users with keyword "美食" (food) or "时尚" (fashion) **Output:** ~19 creators per page with follower counts, verification, bio, avatar, secUid **Use:** Build a ranked KOL shortlist in 5 minutes instead of 5 hours of manual scrolling. #### 2. China Market-Entry Research **Market intelligence analysts** monitoring short-video trends before launching a brand in China. **Input:** Search Videos with industry keyword across 10 pages **Output:** 120+ videos with engagement metrics, captions, hashtags, posting times, music **Use:** Spot trending themes, viral content patterns, and competitor activity weeks before launch. #### 3. Content Trend Tracking **Content strategists** at agencies tracking viral videos, breakout creators, and emerging hashtags daily. **Input:** Scheduled Search Videos run with niche keyword **Output:** Time-series of trending content + engagement velocity **Use:** Feed a trend dashboard or alert system; spot virality 24–48 hours before mainstream. #### 4. Deep Comment Sentiment Mining (Top-Level + Reply Threads) **NLP / brand-perception teams** analyzing reactions on competitor videos or branded-content collaborations. **Input:** Video Comments → identify high-engagement comments → Video Sub-Comments on each **Output:** All top comments + full reply trees with author, location, like counts **Use:** Top-level comments are noisy; **nested replies are where the real conversation lives**. Pipe to a sentiment model to gauge true audience reaction. #### 5. Creator Catalog Mapping (KOL Audit) **Influencer-marketing agencies** doing due diligence on a creator before signing them. **Input:** User Videos operation across 10–20 pages for the creator's secUid **Output:** Full posting history with play/like/share counts and timestamps **Use:** Audit posting cadence, engagement drift, fake-fan red flags, and content quality at scale. #### 6. Brand Monitoring on Douyin **Brand managers** tracking unauthorized mentions, branded-content performance, and counterfeits. **Input:** Search Videos with brand or product keyword scheduled hourly **Output:** Every new mention with creator + engagement **Use:** React to viral mentions in near real-time; flag counterfeits & PR risks. #### 7. Douyin Video Data for Content Re-purposing & Research **Editors, researchers, & creators** working with public Douyin videos for commentary, education, or research. **Input:** Video Detail by ID **Output:** HTTPS-ready `videoUrl` + cover + music + full engagement stats **Use:** Archive, repurpose, or analyze video content programmatically. *** ### 🔗 Integration Examples #### JavaScript/Node.js ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('sian.agency/douyin-scraper').call({ operation: 'searchVideo', keyword: '美食', maxPages: 3, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items[0]); ``` #### Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_TOKEN') run = client.actor('sian.agency/douyin-scraper').call( run_input={'operation': 'userVideos', 'secUid': 'MS4wLjAB...', 'maxPages': 5} ) for item in client.dataset(run['defaultDatasetId']).iterate_items(): print(item) ``` #### cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/sian.agency~douyin-scraper/runs?token=YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"operation":"videoDetail","videoId":"7615930241370348219"}' ``` #### Automation Workflows (N8N / Zapier / Make) 1. **Trigger**: schedule daily or webhook from a brief-creator 2. **HTTP Request**: call the actor's run-sync endpoint with `operation` + input 3. **Process**: filter by `_operation` and pivot on `videoId` / `secUid` / `commentId` 4. **Action**: push to BigQuery, Notion, Airtable, or a Slack alert *** ### 📊 Performance & Pricing #### FREE Tier (Try It Now) - **Full feature access** — every operation, every field, no quality compromise - No credit card required - Perfect for evaluating data depth before you commit #### PAID Tier (Production Ready) - **Unlimited** results per run - Faster processing — no FREE-tier throttling - Pay-per-result: only charged for successful rows, never for errors or empty pages - Volume discounts up to 50% off at GOLD/PLATINUM/DIAMOND Apify tiers 💰 **Best price on the market for premium Douyin data** — see pricing tab for the full per-event ladder. Single-row operations (Video Detail, User Profile) carry richer payloads at premium pricing; bulk operations (Search, User Videos, Comments, Sub-Comments) are priced to scale with you. 🔗 [View current pricing](https://apify.com/sian.agency/douyin-scraper?fpr=sian) *** ### ❓ Frequently Asked Questions **Q: How many videos / users / comments can I extract per run?** A: FREE tier: full feature access for evaluation. PAID tier: unlimited — capped only by `maxPages` (default 5, max 50) and platform-side data availability. **Q: Does it work with private profiles or shadow-banned accounts?** A: No — only publicly accessible Douyin content is supported. Private accounts and banned users return empty or error rows. **Q: What output formats are available?** A: JSON, CSV, Excel, RSS, HTML, XML — export directly from the Apify dataset UI or via API. **Q: Are video URLs permanent?** A: Douyin CDN URLs typically expire after a few hours. Use `videoUrlList` for fallback mirrors, or re-run Video Detail when you need a fresh URL. **Q: Why are Douyin video IDs 19 digits — does the dataset preserve them?** A: Yes. We use a bigint-safe JSON parser so 19-digit IDs (`aweme_id`, `uid`, `cid`) round-trip without precision loss. Most scrapers silently corrupt these and break cross-operation joins. **Q: How do I find a `secUid`?** A: Visit any Douyin profile and copy the trailing segment of the URL (`https://www.douyin.com/user/{SEC_UID}`). The sec UID starts with `MS4wLjAB...` and is found in any video/comment result row's `secUid` field. **Q: Can I search in Chinese?** A: Absolutely — Chinese queries surface the most relevant native Douyin creators. English and mixed queries also work. **Q: What's the difference between Video Comments and Video Sub-Comments?** A: `Video Comments` returns top-level comments on a video. `Video Sub-Comments` returns the reply thread underneath a specific top-level comment. Use the workflow: run `Video Comments` first → grab comment IDs with `replyCount > 0` → run `Video Sub-Comments` for each. **Q: Is this legal?** A: Yes — we only extract publicly available data. See the [Legal section](#-is-it-legal-to-scrape-data) below. **Q: How long does processing take?** A: ~3–10 seconds per page for paginated operations; ~2–5 seconds for single-row operations. *** ### 🐛 Troubleshooting **Page returned no rows / empty dataset** - Verify the input is correct: video ID is 19 digits, secUid starts with `MS4wLjAB`, keyword is non-empty - Check that the video/user still exists on Douyin (try opening `videoPageUrl` or `userPageUrl` from a result row) - For sub-comments: the comment must have `replyCount > 0` to return reply data **HTTP errors / "Data source temporarily unavailable" rows** - The actor auto-retries transient failures up to 4 times with backoff. If you still see error rows, the upstream is rate-limited or down — retry the run after a few minutes. **19-digit video IDs look truncated in spreadsheet exports** - Spreadsheet apps (Excel, Google Sheets) auto-cast long integers to scientific notation. The actor preserves them as strings in JSON; in CSV exports, format the `videoId` column as Text before opening. **Pagination ends earlier than `maxPages` requested** - That means the platform served the last page. Check `_page` on the last row — `isLastPage` was true. Not all creators or keywords have 50 pages of content. *** ### ⚠️ Trademark Disclaimer This actor is an **independent scraping tool** and is not affiliated with, endorsed by, or sponsored by Beijing Microlive Vision Technology Co., Ltd., Douyin, ByteDance Ltd., or any of its subsidiaries. "Douyin" and "TikTok China" are used solely in a descriptive sense to identify the public data source the actor reads from. **Douyin®** and **TikTok®** are trademarks of their respective owners. All other trademarks are the property of their respective owners. *** ### ⚖️ Is it legal to scrape data? Our actors are ethical and do not extract any private user data, such as email addresses or private contact information. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the **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. You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/). *** ### ✨ More by SIÁN Agency Part of the SIÁN Agency Apify portfolio — production-grade scrapers and AI tools used by agencies, research teams, and brands. A few that pair well with Douyin: **China & E-commerce** - [Kwai & Kuaishou Scraper](https://apify.com/sian.agency/kwai-kuaishou-scraper?fpr=sian) — China's #2 short-video platform: videos, profiles, comments, search - [Taobao & Tmall Product Scraper](https://apify.com/sian.agency/taobao-tmall-product-scraper?fpr=sian) — China's #1 marketplace: products, search, shop catalogs, reviews - [Uber Eats Menu Scraper](https://apify.com/sian.agency/uber-eats-menu-scraper?fpr=sian) — restaurant menus + prices **Short-Video & Social Media** - [Best TikTok AI Transcript Extractor](https://apify.com/sian.agency/best-tiktok-ai-transcript-extractor?fpr=sian) — international TikTok video → text with metadata - [Instagram AI Transcript Extractor](https://apify.com/sian.agency/instagram-ai-transcript-extractor?fpr=sian) — Reels & Stories transcription - [Facebook AI Transcript Extractor](https://apify.com/sian.agency/facebook-ai-transcript-extractor?fpr=sian) — Facebook video → text - [YouTube Shorts AI Transcript & Metadata Extractor](https://apify.com/sian.agency/youtube-shorts-ai-transcript-and-metadata-extractor?fpr=sian) — Shorts data + transcripts **Real Estate (Global)** - [Bayut (Dubai)](https://apify.com/sian.agency/bayut-property-scraper?fpr=sian) · [Idealista (Spain)](https://apify.com/sian.agency/smart-idealista-scraper?fpr=sian) [Browse all SIÁN actors →](https://apify.com/sian.agency?fpr=sian) *** ### ⭐ Leave a 5-Star Review Love this actor? **[Leave a 5-star review here](https://apify.com/sian.agency/douyin-scraper/reviews)** — it helps us build more features for you and lets other teams find it. *** ### 🤝 Support [![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi) **Join our active support community** - For issues or questions, open an issue in the actor's Apify Console Issues tab - 📧 *** **Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)** # Actor input Schema ## `operation` (type: `string`): 🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode. - **🎥 Video Detail** — deep scrape of a single Douyin video by ID (caption, play/like/share/comment counts, video URLs, cover, music, creator info) - **👤 User Profile** — full profile by Sec UID (followers, total likes, post count, bio, verification, location, avatars) - **📹 User Videos** — paginated list of a creator's full video history (~20 videos/page) - **💬 Video Comments** — paginated top-level comments on a single video (~20 comments/page) - **🧵 Video Sub-Comments** — paginated reply threads under a specific comment (~10 replies/page) - **🔍 Search Videos** — keyword search across Douyin videos, paginated (~12 results/page) - **🔎 Search Users** — keyword search across Douyin creators, paginated (~19 results/page) 💡 **TIP:** To combine operations (e.g. search → drill into top creators), run the actor multiple times with different configurations. ## `videoId` (type: `string`): 🎥 **Required for `Video Detail`, `Video Comments`, and `Video Sub-Comments` operations.** The numeric Douyin video ID (also called `aweme_id`). You can find it: - In any Douyin video URL: `https://www.douyin.com/video/{ID}` → the trailing segment - In the `videoId` / `aweme_id` field of any search or user-videos result row 💡 **TIP:** To analyze a batch of videos, run a `Search Videos` operation first, copy the `videoId` values, then run `Video Detail` or `Video Comments` per ID. ⚠️ **Ignored** for User Profile, User Videos, and Search operations. ## `commentId` (type: `string`): 💬 **Required for `Video Sub-Comments` operation only.** The numeric comment ID (also called `cid`) whose reply thread you want to extract. You can find it: - In the `commentId` / `cid` field of any `Video Comments` result row - Only comments with `replyCount > 0` will return reply data 💡 **TIP:** Run `Video Comments` first to identify high-engagement comments, then run `Video Sub-Comments` with those comment IDs to pull the full conversation tree. ⚠️ **Ignored** for all other operations. ## `secUid` (type: `string`): 👤 **Required for `User Profile` and `User Videos` operations.** The Douyin `sec_uid` — an encrypted user handle starting with `MS4wLjAB...`. You can find it: - In the `secUid` / `sec_uid` field of any video, search, or comment result row - In a creator's profile URL: `https://www.douyin.com/user/{SEC_UID}` 💡 **TIP:** To build a list of creators in a niche, run `Search Users` with a keyword first, then use the top `secUid` values to drill into individual profiles or video catalogs. ⚠️ **Ignored** for Video Detail, Comments, and Search operations. ## `keyword` (type: `string`): 🔍 **Required for `Search Videos` and `Search Users` operations.** Any Douyin search query. Supports Chinese, English, and mixed queries: - `美食` (food) - `搞笑视频` (funny videos) - `dance` - `fashion` 💡 **TIP:** Chinese-language queries surface the most relevant native Douyin creators. Specific niches return higher-quality results than broad terms. ## `maxPages` (type: `integer`): 📄 **Applies to paginated operations** (User Videos, Video Comments, Video Sub-Comments, Search Videos, Search Users). Ignored for single-record operations (Video Detail, User Profile). - **User Videos:** ~20 videos per page - **Video Comments:** ~20 comments per page - **Video Sub-Comments:** ~10 replies per page - **Search Videos:** ~12 results per page - **Search Users:** ~19 results per page 💡 **TIP:** Start small (1–3 pages) to preview results before scaling up. ⚠️ Hard cap: 50 pages to prevent runaway runs. ## Actor input object example ```json { "operation": "searchVideo", "videoId": "7615930241370348219", "commentId": "7615932448664650533", "secUid": "MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "keyword": "美食", "maxPages": 5 } ``` # Actor output Schema ## `output` (type: `string`): Videos, profiles, comments, sub-comments, or search results — one flat row per upstream item with curated camelCase aliases (videoId, secUid, userName, playCount, likeCount, caption, postedAt, videoUrl, coverUrl, avatarUrl, …) plus the raw upstream fields spread alongside. ## `report` (type: `string`): HTML report with run status, success/error row counts, success rate, pages fetched, duration, and the inputs used — written even on fatal crash. # 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 = { "videoId": "7615930241370348219", "commentId": "7615932448664650533", "secUid": "MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "keyword": "美食" }; // Run the Actor and wait for it to finish const run = await client.actor("sian.agency/douyin-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 = { "videoId": "7615930241370348219", "commentId": "7615932448664650533", "secUid": "MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "keyword": "美食", } # Run the Actor and wait for it to finish run = client.actor("sian.agency/douyin-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 '{ "videoId": "7615930241370348219", "commentId": "7615932448664650533", "secUid": "MS4wLjABAAAAUT_tvNpyI5-tObkvU2xaaqyeDpek5UJXLG8mePjYxTQ", "keyword": "美食" }' | apify call sian.agency/douyin-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sian.agency/douyin-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Douyin Scraper — TikTok China API & Video Downloader", "description": "Douyin scraper for TikTok China — extract video data, user profiles, comments, reply threads, and keyword search. KOL discovery, view counts, engagement metrics, China market research. Seven operations, one clean dataset per run. No API key.", "version": "1.0", "x-build-id": "oh07LukyrqUvkqEqR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sian.agency~douyin-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sian.agency-douyin-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/sian.agency~douyin-scraper/runs": { "post": { "operationId": "runs-sync-sian.agency-douyin-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/sian.agency~douyin-scraper/run-sync": { "post": { "operationId": "run-sync-sian.agency-douyin-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", "required": [ "operation" ], "properties": { "operation": { "title": "🎯 Operation — what do you want to scrape?", "enum": [ "videoDetail", "userDetail", "userVideos", "videoComments", "videoSubComments", "searchVideo", "searchUser" ], "type": "string", "description": "🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode.\n\n- **🎥 Video Detail** — deep scrape of a single Douyin video by ID (caption, play/like/share/comment counts, video URLs, cover, music, creator info)\n- **👤 User Profile** — full profile by Sec UID (followers, total likes, post count, bio, verification, location, avatars)\n- **📹 User Videos** — paginated list of a creator's full video history (~20 videos/page)\n- **💬 Video Comments** — paginated top-level comments on a single video (~20 comments/page)\n- **🧵 Video Sub-Comments** — paginated reply threads under a specific comment (~10 replies/page)\n- **🔍 Search Videos** — keyword search across Douyin videos, paginated (~12 results/page)\n- **🔎 Search Users** — keyword search across Douyin creators, paginated (~19 results/page)\n\n💡 **TIP:** To combine operations (e.g. search → drill into top creators), run the actor multiple times with different configurations.", "default": "searchVideo" }, "videoId": { "title": "🎥 Video ID (for Video Detail / Comments / Sub-Comments)", "type": "string", "description": "🎥 **Required for `Video Detail`, `Video Comments`, and `Video Sub-Comments` operations.**\n\nThe numeric Douyin video ID (also called `aweme_id`). You can find it:\n- In any Douyin video URL: `https://www.douyin.com/video/{ID}` → the trailing segment\n- In the `videoId` / `aweme_id` field of any search or user-videos result row\n\n💡 **TIP:** To analyze a batch of videos, run a `Search Videos` operation first, copy the `videoId` values, then run `Video Detail` or `Video Comments` per ID.\n\n⚠️ **Ignored** for User Profile, User Videos, and Search operations." }, "commentId": { "title": "💬 Comment ID (for Video Sub-Comments)", "type": "string", "description": "💬 **Required for `Video Sub-Comments` operation only.**\n\nThe numeric comment ID (also called `cid`) whose reply thread you want to extract. You can find it:\n- In the `commentId` / `cid` field of any `Video Comments` result row\n- Only comments with `replyCount > 0` will return reply data\n\n💡 **TIP:** Run `Video Comments` first to identify high-engagement comments, then run `Video Sub-Comments` with those comment IDs to pull the full conversation tree.\n\n⚠️ **Ignored** for all other operations." }, "secUid": { "title": "👤 Sec UID (for User Profile / User Videos)", "type": "string", "description": "👤 **Required for `User Profile` and `User Videos` operations.**\n\nThe Douyin `sec_uid` — an encrypted user handle starting with `MS4wLjAB...`. You can find it:\n- In the `secUid` / `sec_uid` field of any video, search, or comment result row\n- In a creator's profile URL: `https://www.douyin.com/user/{SEC_UID}`\n\n💡 **TIP:** To build a list of creators in a niche, run `Search Users` with a keyword first, then use the top `secUid` values to drill into individual profiles or video catalogs.\n\n⚠️ **Ignored** for Video Detail, Comments, and Search operations." }, "keyword": { "title": "🔍 Search Keyword (for Search Videos / Search Users)", "type": "string", "description": "🔍 **Required for `Search Videos` and `Search Users` operations.**\n\nAny Douyin search query. Supports Chinese, English, and mixed queries:\n- `美食` (food)\n- `搞笑视频` (funny videos)\n- `dance`\n- `fashion`\n\n💡 **TIP:** Chinese-language queries surface the most relevant native Douyin creators. Specific niches return higher-quality results than broad terms." }, "maxPages": { "title": "📄 Max pages to fetch", "minimum": 1, "maximum": 50, "type": "integer", "description": "📄 **Applies to paginated operations** (User Videos, Video Comments, Video Sub-Comments, Search Videos, Search Users). Ignored for single-record operations (Video Detail, User Profile).\n\n- **User Videos:** ~20 videos per page\n- **Video Comments:** ~20 comments per page\n- **Video Sub-Comments:** ~10 replies per page\n- **Search Videos:** ~12 results per page\n- **Search Users:** ~19 results per page\n\n💡 **TIP:** Start small (1–3 pages) to preview results before scaling up.\n\n⚠️ Hard cap: 50 pages to prevent runaway runs.", "default": 5 } } }, "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 } } } } } } } } } } ```