# Douyin Scraper — 抖音 Search, Videos, Users & Comments (`logiover/douyin-scraper`) Actor

Scrape Douyin (抖音, China's TikTok) without login: keyword video search, user search, video details by URL, comments, profiles and the hot-search boards. Videos with likes, comments, shares, saves, hashtags, music, cover and video URL, plus the author's followers and IP location.

- **URL**: https://apify.com/logiover/douyin-scraper.md
- **Developed by:** [Logiover](https://apify.com/logiover) (community)
- **Categories:** Social media
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.30 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Douyin Scraper — 抖音 Video Search, Users, Comments & Hot Search Data (抖音数据采集)

**Scrape Douyin (抖音, China's TikTok) without logging in: search videos and creators by keyword, pull full video details and comments from links, read creator profiles, and export the hot-search boards (抖音热榜) — clean rows with likes, comments, shares, saves, hashtags, music, cover, video URL and the author's real follower numbers.**

**Douyin Scraper** is a Douyin data extractor (抖音数据采集 / 抖音爬虫 / 抖音视频采集 / 抖音搜索采集 / 抖音评论采集 / 抖音达人数据 / 抖音热榜数据) that turns Douyin's own search into a spreadsheet. Type a keyword such as 美食 (food), 旅行 (travel), 穿搭 (outfits), 美妆 (beauty), 健身 (fitness), 宠物 (pets) or a brand name, and the Actor returns every video Douyin's search shows for it — caption, separate title, hashtags in their original spelling, @-mentions, publish time, like count (点赞), comment count (评论), share count (分享/转发), save count (收藏), duration, cover and animated cover, a playable video URL, every image of an image post (图文), the background music (title, author, original-sound flag), the province the post was published from, and the creator: Douyin ID (抖音号), nickname, bio, followers (粉丝), following, total likes received (获赞), video count (作品), IP location (IP属地) and verification label. It is a **Douyin API alternative** for people who do not have (or cannot get) access to the Douyin Open Platform: no API key, no app review, no login and no cookies on your side — and you can **export Douyin data to CSV, Excel or JSON** or push it into Google Sheets, a database, a BI tool or an AI agent.

Beyond keyword video search the same Actor does five more jobs: **Douyin user search** (find creators/KOLs for a keyword with Douyin's own follower-range and account-type filters — the classic 抖音达人搜索 for influencer marketing), **Douyin video details by URL** (paste www.douyin.com/video links, v.douyin.com short links from the share button, or bare video ids), **Douyin comment scraping** (top-level comments with text, likes, reply counts, the commenter and their IP location — 抖音评论采集 for sentiment and VOC research), **Douyin profile scraping** by profile link, sec_uid or Douyin ID, and the **Douyin hot search list** (热榜, 娱乐榜, 社会榜, 挑战榜) with heat values. Use it for China social-media monitoring, influencer discovery, competitor and brand tracking, trend research, short-video content analysis, academic studies of Chinese social media, or to build datasets of Chinese-language short-video metadata.

All numbers on this page were measured on the Apify platform on **25 October 2026** (see [Scale and speed](#scale-and-speed-measured-25-october-2026)).

> **Disclaimer:** This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Douyin, ByteDance or Beijing Douyin Information Service Co., Ltd. "Douyin" and 抖音 are trademarks of their respective owners. The Actor reads only information that Douyin shows publicly to any visitor who is not logged in.

***

### Table of contents

- [At a glance](#at-a-glance)
- [What you get: the Douyin data fields](#what-you-get-the-douyin-data-fields)
- [The six modes](#the-six-modes)
- [Who uses this Douyin scraper](#who-uses-this-douyin-scraper)
- [Cookbook: 16 ready-to-run inputs](#cookbook-16-ready-to-run-inputs)
- [Keyword cheat-sheet: what to type for each vertical](#keyword-cheat-sheet-what-to-type-for-each-vertical)
- [Tutorial: scrape Douyin in the Apify Console](#tutorial-scrape-douyin-in-the-apify-console)
- [Tutorial: scrape Douyin with the API](#tutorial-scrape-douyin-with-the-api)
- [Input reference](#input-reference)
- [Output data dictionary (with measured fill rates)](#output-data-dictionary-with-measured-fill-rates)
- [Real output sample](#real-output-sample)
- [How the access works](#how-the-access-works)
- [Scale and speed (measured 25 October 2026)](#scale-and-speed-measured-25-october-2026)
- [Data quality: how the rows were checked](#data-quality-how-the-rows-were-checked)
- [What you pay](#what-you-pay)
- [Integrations](#integrations)
- [Performance tips](#performance-tips)
- [Troubleshooting: every status message explained](#troubleshooting-every-status-message-explained)
- [Honest limits](#honest-limits)
- [Comparison: Douyin Open Platform, manual copying and this Actor](#comparison-douyin-open-platform-manual-copying-and-this-actor)
- [FAQ](#faq)
- [Glossary](#glossary)
- [Is it legal to scrape Douyin?](#is-it-legal-to-scrape-douyin)
- [Changelog](#changelog)
- [Support](#support)

***

### At a glance

| | |
|---|---|
| **What you type** | Keywords in Chinese or English (美食, 旅行, 露营, iPhone) — or Douyin video links, profile links, sec_uid values or Douyin IDs (抖音号) |
| **What you get** | One row per video (or user, comment, profile, hot-search entry): ids and links, caption and title, hashtags, mentions, publish time, likes, comments, shares, saves, duration, cover, video URL, images, music, author with followers / likes / video count / IP location / verification, publish province, keyword and rank |
| **Modes** | Search videos · Search users · Video details by URL · Comments · Profiles · Hot search boards |
| **Scale** | Measured: **10,346 unique videos from 110 keywords in one run (16 min 48 s), 0 duplicates**; 1,000 videos in 55 s |
| **Speed** | First rows ~5 s after start; 20 videos in ~11 s; about 10 videos per second on big runs (author profiles included) |
| **Quality** | Every number is copied from Douyin's own answers; 11 videos and 1 profile were checked by hand against douyin.com pages (see [Data quality](#data-quality-how-the-rows-were-checked)) |
| **Formats** | JSON, CSV, Excel, XML, HTML table, RSS; API, webhooks, Make, Zapier, n8n, Google Sheets, Airtable |
| **Price** | Pay per result: $3.50 per 1,000 on the Free plan, down to $2.30 per 1,000 on higher Store tiers |
| **Needs** | Nothing: no Douyin account, no cookies, no API key, no proxy setup |

***

### What you get: the Douyin data fields

Rows are flat and spreadsheet-friendly. Missing values are `null` — never an empty string or an invented `0`. Times are ISO 8601 UTC (the page's Beijing time 2026-09-29 14:00 is `2026-09-29T06:00:00.000Z`). Chinese text stays UTF-8. Full dictionary with fill rates [further down](#output-data-dictionary-with-measured-fill-rates).

- **Identity and links** — `awemeId` (Douyin's video id, the de-duplication key), `url` (`/video/<id>` or `/note/<id>` for image posts), `shareUrl`, `mediaType` (`video` / `images`).
- **Text** — `desc` (the full caption), `title` (the separate 作品标题 when set), `hashtags` in the caption's own spelling, `mentions` (`{secUid, nickname, url}`).
- **Engagement** — `diggCount` (点赞), `commentCount` (评论), `shareCount` (分享), `collectCount` (收藏) as exact integers (the page shows 21.3万, the row 212,491), `createTime` / `createTimeUnix`.
- **Media** — `durationSec`, `width`, `height`, `coverUrl`, `dynamicCoverUrl`, `videoUrl` (a signed MP4 link that expires), `images` + `imageCount` for 图文; music: `musicId`, `musicTitle`, `musicAuthor`, `musicIsOriginal`, `musicDurationSec`, `musicCoverUrl`.
- **Creator** — `authorUid`, `authorSecUid`, `authorUniqueId` (抖音号), `authorNickname`, `authorUrl`, `authorAvatarUrl`, `authorRegion`, `authorVerification`; from the author's profile (on by default, because Douyin hides these numbers in search results): `authorFollowers` (the 粉丝 number the profile page shows), `authorFollowing`, `authorTotalLikes` (获赞), `authorVideoCount` (作品), `authorIpLocation` (IP属地), `authorSignature`.
- **Place** — `postCityCode` (the six-digit administrative code Douyin tags the post with, e.g. `330100` Hangzhou) and `postProvince` (`浙江省`, from the national GB/T 2260 table).
- **Search context** — `keyword`, `searchTab` (`video` or `general`), `rank` (position in that keyword's results), `scrapedAt`.

***

### The six modes

| Mode (`mode`) | Input | One row per | Typical use |
|---|---|---|---|
| **Search videos** (`search`) | `keywords` | video / image post | Trend and content research, brand monitoring, building datasets |
| **Search users** (`users`) | `keywords` (+ follower range, account type) | creator account | Influencer / KOL discovery, lead lists, competitor accounts |
| **Video details** (`videos`) | `urls` (video links, short links, ids) | video | Refreshing stats of known videos, enriching link lists |
| **Comments** (`comments`) | `urls` (video links or ids) | comment | Sentiment, VOC, community research, moderation studies |
| **Profiles** (`profiles`) | `urls` (profile links, sec_uid, Douyin ID) | profile | Creator due diligence, follower tracking, CRM enrichment |
| **Hot search** (`trending`) | `trendingBoards` | hot-search entry | Trend monitoring, news and PR desks, content calendars |

Search videos reads two of Douyin's search tabs for each keyword — the **video tab** (视频, 20 per page) and the **general tab** (综合, 10 per page) — and keeps every video once. With **Add related keywords** on, it also searches the related keywords Douyin suggests under the results (相关搜索), which turns one seed keyword into a topic-wide dataset (measured: 露营 plus 5 related keywords → 400 unique videos in 21 s).

***

### Who uses this Douyin scraper

#### 1. Influencer marketing agencies — "the 200 fitness creators worth a brief"

Search users for 健身, 减脂, 瑜伽 with the follower range 10w–100w, keep profiles on, and sort by `totalLikes` / `followers`. Every row has the Douyin ID (抖音号), bio (often with a business contact the creator published), IP location and verification label, so a shortlist is one filter away.

#### 2. Brand managers watching China — "what people post about us this week"

Search videos for the brand name in Chinese and English (e.g. 瑞幸, luckin), weekly on a schedule. `createTime`, likes and comments show which posts move; `authorFollowers` separates creators from ordinary customers.

#### 3. Cross-border e-commerce sellers — "which products trend on Douyin"

Keywords like 好物推荐, 开箱, 测评 plus your category (蓝牙耳机, 空气炸锅) return the videos that sell; hashtags and music show the formats that work. Pair with comments to read real objections.

#### 4. Social listening and VOC analysts — "10,000 comments, structured"

Collect the top videos for a topic, then run Comments mode on their links: every comment with likes, reply count, the commenter's IP province and time — ready for sentiment models.

#### 5. Trend researchers and content strategists — "what is hot right now"

Hot search mode exports the 热榜, 娱乐榜, 社会榜 and 挑战榜 boards (about 50 entries each) with heat values; run it hourly to chart how topics rise and fall, then search the hot words for the videos behind them.

#### 6. Academic researchers — "a reproducible sample of Chinese short video"

Keyword lists in, ids out: `awemeId`, `rank`, `keyword` and `scrapedAt` make a dataset citable and re-collectable; provinces and IP locations support regional analyses.

#### 7. Newsrooms and fact-checkers — "find the first uploads of a viral clip"

Search the event's keywords, sort by `createTime`, open the earliest posts; the hot-search board's `eventTime` shows when Douyin started ranking a topic.

#### 8. Music labels and promoters — "which songs soundtrack the category"

`musicTitle`, `musicAuthor` and `musicIsOriginal` across thousands of videos show which tracks creators choose in a niche — and which creators use original sound.

#### 9. Tourism boards and travel brands — "what travellers film in our city"

Search 城市名 + 旅游攻略 / 打卡 / 美食; `postProvince` confirms where posts were published, image posts (`images`) carry the itineraries people share.

#### 10. Food and restaurant chains — "how our dishes look in user videos"

探店 (store visit) and dish keywords return reviews by local creators, their audience size, and the comment counts that show engagement.

#### 11. Automotive marketers — "car content by audience size"

Keywords such as 新能源汽车, 试驾, 二手车 give the model reviews and dealer accounts; verification labels identify official dealer and brand accounts (企业认证).

#### 12. AI and LLM teams — "grounded Chinese short-video data"

Captions, titles, hashtags and comments in natural Chinese, with ids for provenance; feed them to retrieval systems or label them for classifiers (MCP-ready through Apify).

#### 13. Community and customer-support teams — "what users complain about under our videos"

Comments mode on your own videos (and competitors') returns the complaints and questions with like counts, in Douyin's own order (its hot ranking: popular comments first, mixed with recent ones).

#### 14. Lead generation for B2B services — "verified businesses in a niche"

Users mode with account type 企业认证 (verified business) and a keyword such as 装修, 律师, 培训 returns company accounts with their verification text (often the registered company name).

***

### Cookbook: 16 ready-to-run inputs

Paste any of these into the JSON tab of the input form.

#### 1. One keyword, quick sample

```json
{ "mode": "search", "keywords": ["美食"], "maxItems": 20 }
```

#### 2. Several keywords, everything Douyin returns

```json
{ "mode": "search", "keywords": ["美食", "旅行", "健身", "穿搭", "美妆", "宠物"], "maxItems": 0 }
```

#### 3. One topic, as deep as possible (related keywords)

```json
{ "mode": "search", "keywords": ["露营"], "expandRelatedKeywords": true, "maxRelatedKeywords": 50, "maxItems": 0 }
```

#### 4. Balanced sample across many keywords

```json
{ "mode": "search", "keywords": ["火锅", "烧烤", "奶茶", "咖啡", "甜品"], "maxItemsPerKeyword": 50, "maxItems": 250 }
```

#### 5. Video tab only (视频)

```json
{ "mode": "search", "keywords": ["咖啡拉花"], "searchTabs": "video", "maxItems": 100 }
```

#### 6. Fastest run (no author profiles)

```json
{ "mode": "search", "keywords": ["数码", "手机"], "includeAuthorProfiles": false, "maxItems": 500 }
```

#### 7. Find creators (KOLs) for a niche

```json
{ "mode": "users", "keywords": ["健身", "减脂", "瑜伽"], "maxItems": 300 }
```

#### 8. Mid-tier creators only (100k–1M followers)

```json
{ "mode": "users", "keywords": ["美妆"], "userFollowers": "10w_100w", "maxItems": 100 }
```

#### 9. Verified businesses in a niche

```json
{ "mode": "users", "keywords": ["装修"], "userType": "enterprise_user", "maxItems": 100 }
```

#### 10. Video details from links (share links work too)

```json
{ "mode": "videos", "urls": ["https://www.douyin.com/video/7690795980844846371", "https://www.douyin.com/note/7651236453369147377", "7673448720423308607"] }
```

v.douyin.com short links and whole share texts copied from the Douyin app ("复制打开抖音，看看… https://v.douyin.com/…/") work in the same list.

#### 11. Comments of a few videos

```json
{ "mode": "comments", "urls": ["https://www.douyin.com/video/7545084134726651193"], "maxCommentsPerVideo": 500 }
```

#### 12. Profiles by link, sec_uid or Douyin ID

```json
{ "mode": "profiles", "urls": ["https://www.douyin.com/user/MS4wLjABAAAA2e4rrQ50J4cC06t4c8IDz1N04l0cnjWahNgkNEVYMfvZvNMHl2BYYZM90y-RgLZx", "XSCF1314"] }
```

#### 13. The hot-search boards (热榜)

```json
{ "mode": "trending", "trendingBoards": ["hot", "entertainment", "society", "challenge"] }
```

#### 14. English keyword, international brand

```json
{ "mode": "search", "keywords": ["iPhone", "苹果手机"], "maxItems": 300 }
```

#### 15. Cap the spend of one run

Set **Maximum cost per run** in the run options (or `maxTotalChargeUsd` in the API) — the run stops cleanly when the budget is used and says so in its status message.

```json
{ "mode": "search", "keywords": ["旅游攻略"], "maxItems": 0 }
```

#### 16. A 10,000-video dataset

```json
{ "mode": "search", "keywords": ["美食", "旅行", "健身", "穿搭", "美妆", "宠物", "汽车", "数码", "搞笑", "舞蹈", "护肤", "猫", "狗", "手机", "游戏", "电影", "音乐", "教育", "英语", "育儿"], "expandRelatedKeywords": true, "maxRelatedKeywords": 100, "maxItems": 10000 }
```

***

### Keyword cheat-sheet: what to type for each vertical

Douyin is a Chinese-language platform: Chinese keywords match far more content than English ones. Short, common words work best; add a second word to narrow down.

| Vertical | Keywords that work (中文关键词) |
|---|---|
| Food | 美食, 家常菜, 探店, 火锅, 烧烤, 小吃, 甜品, 减脂餐, 早餐, 美食教程 |
| Drinks | 咖啡, 奶茶, 茶, 白酒, 精酿, 咖啡拉花 |
| Travel | 旅行, 旅游攻略, 自驾游, 民宿, 露营, 徒步, 打卡, 城市名 + 旅游 |
| Beauty | 美妆, 护肤, 化妆教程, 发型, 美甲, 口红, 防晒 |
| Fashion | 穿搭, 汉服, 古风, 男装, 女装, 鞋 |
| Fitness | 健身, 减脂, 瘦身, 瑜伽, 跑步, 健身教程, 普拉提 |
| Pets | 宠物, 猫, 狗, 萌宠, 金毛, 布偶猫 |
| Tech | 数码, 手机, 电脑, 测评, 开箱, AI, 编程 |
| Cars | 汽车, 新能源汽车, 试驾, 二手车, 汽车改装 |
| Home | 家居, 装修, 收纳, 园艺, 花卉 |
| Parenting & education | 育儿, 亲子, 教育, 英语, 考研, 高考, 留学 |
| Money & work | 理财, 股票, 创业, 职场, 面试 |
| Entertainment | 搞笑, 舞蹈, 唱歌, 电影, 动漫, 游戏, 魔术 |
| Shopping intent | 好物推荐, 开箱, 测评, 平替, 种草 |

Brand names work in either script (`iPhone`, `苹果`, `华为`, `小米`, `瑞幸`), and so do creator names and Douyin IDs.

***

### Tutorial: scrape Douyin in the Apify Console

1. Open the Actor and press **Try for free** (or **Start** if you already use it).
2. In **What to scrape**, keep **Search videos by keyword**.
3. Type one keyword per line into **Search keywords**, e.g. `美食` and `旅行`.
4. Set **Max results** — 100 for a first look, `0` for everything Douyin returns.
5. Optional: turn on **Add related keywords (相关搜索)** for a deeper topic dataset, or turn off **Include author profiles** for the fastest run.
6. Press **Start**. Rows appear in the **Output** tab within seconds; the status line counts them.
7. When the run finishes, open **Export** and download **CSV**, **Excel** or **JSON** — or open the dataset views (Videos, Users, Comments, Profiles, Hot search) for a table of the most useful columns.
8. To repeat it, save the input as a **Task** and add a **Schedule** (hourly, daily, weekly).

Other modes: pick them in **What to scrape** and fill **Douyin URLs or IDs** or **Hot search boards**.

***

### Tutorial: scrape Douyin with the API

Start a run and wait for it (replace `YOUR_TOKEN`; the Actor's API name is shown on its page):

```bash
curl -X POST "https://api.apify.com/v2/acts/<ACTOR_ID>/run-sync-get-dataset-items?token=YOUR_TOKEN&format=json" \
  -H "Content-Type: application/json" \
  -d '{"mode":"search","keywords":["美食"],"maxItems":100}' > douyin_videos.json
```

Node.js with `apify-client`:

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('<ACTOR_ID>').call({
    mode: 'search',
    keywords: ['美食', '旅行'],
    maxItems: 500,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const v of items) console.log(v.awemeId, v.diggCount, v.authorNickname, v.authorFollowers);
```

Python with `apify-client`:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("<ACTOR_ID>").call(run_input={
    "mode": "users",
    "keywords": ["健身"],
    "userFollowers": "10w_100w",
    "maxItems": 100,
})
for user in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(user["nickname"], user["uniqueId"], user["followers"], user["ipLocation"])
```

CSV straight from the dataset: `https://api.apify.com/v2/datasets/<DATASET_ID>/items?format=csv&clean=true` (add `&fields=awemeId,url,desc,diggCount,authorNickname` to choose columns). The run's `SUMMARY` record in the default key-value store explains how the run ended (outcome, rows saved, keywords, requests by route).

***

### Input reference

| Field | Type | Default | Meaning |
|---|---|---|---|
| `mode` | string | `search` | `search`, `users`, `videos`, `comments`, `profiles` or `trending` (see [The six modes](#the-six-modes)) |
| `keywords` | array of strings | `[]` | Keywords for `search` and `users` (one per line in the form). Also accepted by `profiles` as Douyin IDs |
| `urls` | array of strings | `[]` | `videos` / `comments`: video links (`/video/…`, `/note/…`, `?modal_id=…`), v.douyin.com short links, share texts that contain one, or bare video ids. `profiles`: profile links, sec_uid (`MS4wLjABAAAA…`), profile short links, or Douyin IDs (抖音号) |
| `maxItems` | integer | `1000` | Total rows to save; `0` = no limit (the run stops when everything is read or at the maximum cost per run) |
| `maxItemsPerKeyword` | integer | `0` | Cap per keyword (spreads a long list evenly); `0` = no cap |
| `searchTabs` | string | `all` | `all` (video tab + general tab), `video` or `general` |
| `expandRelatedKeywords` | boolean | `false` | Also search Douyin's related keywords (相关搜索) found under the results |
| `maxRelatedKeywords` | integer | `30` | How many related keywords may be added (0–500) |
| `includeAuthorProfiles` | boolean | `true` | Read each author's profile once for followers, following, likes, video count, bio and IP location (videos, users) |
| `userFollowers` | string | `""` | Users mode: `0_1k`, `1k_1w`, `1w_10w`, `10w_100w`, `100w_` (Douyin's 粉丝数量 filter) |
| `userType` | string | `""` | Users mode: `common_user` (普通用户), `enterprise_user` (企业认证), `personal_user` (个人认证) |
| `maxCommentsPerVideo` | integer | `100` | Comments mode: top-level comments per video (1–100,000) |
| `trendingBoards` | array | `["hot"]` | Hot search mode: any of `hot`, `entertainment`, `society`, `challenge` |
| `proxyConfiguration` | object | no proxy | Leave as is — the Actor picks its route itself. Set it only to force every request through your own proxy |

***

### Output data dictionary (with measured fill rates)

Fill rate = share of rows where the field has a value. Video fields were measured on the **10,346-row search run of 25 October 2026** (110 keywords, default settings); the four fields changed in version 1.0 after that run are marked † and measured on a 400-row run of the final build. Fields that only apply to one kind of post (videos vs image posts) are filled for 100 % of that kind.

#### Videos (modes `search` and `videos`)

| Field | Type | Meaning | Fill | Example |
|---|---|---|---|---|
| `awemeId` | string | Douyin video id | 100 % | `7690795980844846371` |
| `url` | string | Canonical video / note page | 100 % | `https://www.douyin.com/video/7690795980844846371` |
| `mediaType` | string | `video` or `images` (图文) | 100 % | `video` (77 %), `images` (23 %) |
| `desc` | string | Full caption with hashtags | 98.8 % | `五毛土豆和两分钱的鸡蛋，…` |
| `title` † | string | Separate title (作品标题), when set | 36–65 % | `五毛土豆和两分钱的鸡蛋，…` |
| `createTime` | string | Publish time, ISO 8601 UTC | 100 % | `2026-09-29T06:00:00.000Z` |
| `createTimeUnix` | number | Publish time, Unix seconds | 100 % | `1790661600` |
| `hashtags` | array | Hashtags in the caption's spelling | 94.0 % | `["下饭菜", "糖醋土豆鸡蛋"]` |
| `mentions` | array | @-mentioned accounts | 5.2 % | `[{"secUid": "MS4w…", "nickname": "…", "url": "…"}]` |
| `diggCount` | number | Likes (点赞) | 100 % | `212491` |
| `commentCount` | number | Comments (评论) | 100 % | `1226` |
| `shareCount` | number | Shares (分享) | 100 % | `44383` |
| `collectCount` | number | Saves (收藏) | 100 % | `99085` |
| `durationSec` | number | Video length in seconds (videos) | 77.0 % (100 % of videos) | `75.3` |
| `width`, `height` | number | Video / image size in pixels | 99.5 % | `1080`, `1920` |
| `coverUrl` | string | Cover image | 100 % | `https://p3-sign.douyinpic.com/…` |
| `dynamicCoverUrl` | string | Animated cover (videos) | 77.0 % (100 % of videos) | `https://p5-…douyinpic.com/obj/…` |
| `videoUrl` | string | Playable MP4 link (signed, expires) | 77.0 % (100 % of videos) | `https://v3-dymsearch.douyinvod.com/…` |
| `images` | array | Image URLs of an image post | 23.0 % (100 % of image posts) | `["https://p3-sign.douyinpic.com/…"]` |
| `imageCount` | number | Number of images | 23.0 % | `9` |
| `musicId` | string | Background music id | 99.4 % | `7690796169777597211` |
| `musicTitle` | string | Music title | 99.4 % | `@夏叔厨房创作的原声` |
| `musicAuthor` | string | Music author | 99.4 % | `夏叔厨房` |
| `musicIsOriginal` | boolean | Original sound flag | 99.4 % | `false` |
| `musicDurationSec` | number | Music length (s) | 99.4 % | `75` |
| `musicCoverUrl` | string | Music cover | 98.1 % | `https://p3.douyinpic.com/…` |
| `authorUid` | string | Author's numeric uid | 100 % | `2273413469048935` |
| `authorSecUid` | string | Author's sec_uid (profile key) | 100 % | `MS4wLjABAAAAYT9oc6rr…` |
| `authorUniqueId` | string | Douyin ID (抖音号) | 100 % | `XSCF1314` |
| `authorNickname` | string | Display name | 100 % | `夏叔厨房` |
| `authorUrl` | string | Profile link | 100 % | `https://www.douyin.com/user/MS4w…` |
| `authorAvatarUrl` | string | Avatar | 100 % | `https://p3.douyinpic.com/aweme/100x100/…` |
| `authorSignature` | string | Bio (from the profile) | 93.1 % | `跟着夏叔学做菜，…` |
| `authorVerification` † | string | Verification label | 5–7 % | `美食自媒体、中国药膳大师` |
| `authorFollowers` † | number | Followers as the profile page shows (粉丝) | 100 % | `23277361` |
| `authorFollowing` | number | Accounts followed (关注) | 100 % | `41` |
| `authorTotalLikes` | number | Likes received (获赞) | 100 % | `337248128` |
| `authorVideoCount` | number | Posts (作品) | 100 % | `1259` |
| `authorIpLocation` | string | IP location (IP属地) | 86.1 % | `天津` |
| `authorRegion` | string | Account region code | 100 % | `CN` |
| `postCityCode` | string | Administrative code of the publish city | 96.5 % | `330100` |
| `postProvince` | string | Province of the publish city | 96.5 % | `浙江省` |
| `shareUrl` | string | Douyin's own share link | 100 % | `https://www.iesdouyin.com/share/video/…` |
| `keyword` | string | Keyword that found it (search mode) | 100 % | `美食` |
| `searchTab` | string | `video` or `general` | 100 % | `video` (68 %), `general` (32 %) |
| `rank` | number | Position in that keyword's results | 100 % | `3` |
| `scrapedAt` | string | Collection time (UTC) | 100 % | `2026-10-24T22:18:45.000Z` |

† `title` was the separate title only from 1.0 on (36 % of the 10,346 rows carried one; 65 % in a 400-row camping sample). `authorVerification` also reads the certification label (account_cert_info) since 1.0. `authorFollowers` is the multi-app number shown on the profile page since 1.0 (before: Douyin's main-app count, which differs by up to a few percent for large accounts).

With `includeAuthorProfiles: false`, the seven profile fields (`authorFollowers`, `authorFollowing`, `authorTotalLikes`, `authorVideoCount`, `authorIpLocation`, `authorSignature` from the profile, `authorVerification` from the profile) stay `null` — Douyin's search answers carry these numbers as 0, and a 0 that is not a measurement is never written.

#### Users (mode `users`) — measured on 205 users from 3 keywords

| Field | Type | Meaning | Fill |
|---|---|---|---|
| `uid`, `secUid`, `uniqueId`, `nickname`, `url`, `avatarUrl` | string | Identity and links | 100 % |
| `followers`, `following`, `totalLikes`, `videoCount`, `likedVideosCount`, `mixCount` | number | Profile counters (粉丝, 关注, 获赞, 作品, 喜欢, 合集) | 100 % |
| `signature` | string | Bio | 95.6 % |
| `ipLocation` | string | IP属地 | 88.8 % |
| `age` | number | Age, when the user shows it | 52.2 % |
| `verification` | string | Verification label | 16.1 % |
| `enterpriseVerification` | string | Business verification (企业认证) text | 9.3 % |
| `isLive` | boolean | Live right now | 100 % |
| `roomId` | string | Live room id when live | 2.9 % |
| `isPrivate` | boolean | Private account | 100 % |
| `keyword`, `rank`, `scrapedAt` | | Search context | 100 % |

#### Comments (mode `comments`) — measured on 600 comments of 3 videos

| Field | Type | Meaning | Fill |
|---|---|---|---|
| `commentId` | string | Comment id (cid) | 100 % |
| `awemeId`, `videoUrl` | string | The video | 100 % |
| `text` | string | Comment text (sticker-only comments have none) | 99.5 % |
| `createTime` | string | Posted (UTC) | 100 % |
| `diggCount` | number | Likes on the comment | 100 % |
| `replyCount` | number | Replies under it | 100 % |
| `ipLocation` | string | Commenter's IP province | 100 % |
| `isHot`, `isAuthorLiked` | boolean | Hot comment; liked by the video's author | 100 % |
| `label` | string | Label such as 作者 (the author's own comment) | 0.2 % |
| `imageUrls` | array | Images in the comment | 3.2 % |
| `userUid`, `userSecUid`, `userUniqueId`, `userNickname`, `userUrl`, `userAvatarUrl`, `userRegion` | string | The commenter | 100 % |
| `rank`, `scrapedAt` | | Order and time | 100 % |

#### Profiles (mode `profiles`)

The user fields above (all from the profile itself) plus `coverUrl` (the profile banner) and `input` (what you entered). Measured on 20 random creators: counters, ids, links, avatar and banner 100 %, `signature` 90 %, `ipLocation` 75 %, `age` 50 %, `verification` 5 %, `roomId` only while live.

#### Hot search (mode `trending`) — measured on 201 entries from 4 boards

| Field | Type | Meaning | Fill |
|---|---|---|---|
| `board` | string | `hot`, `entertainment`, `society`, `challenge` | 100 % |
| `rank` | number | Position (the pinned entry has none) | 99.5 % |
| `word` | string | The topic | 100 % |
| `hotValue` | number | Heat (热度) | 99.5 % |
| `videoCount`, `viewCount` | number | Videos and views Douyin attributes to the topic | 99.5 %, 99.5 % |
| `eventTime` | string | When the topic started (UTC) | 99.5 % |
| `sentenceId`, `groupId` | string | Douyin's topic ids | 100 %, 99.5 % |
| `labelCode`, `labelIconUrl` | number, string | Douyin's badge (热, 新 …) code and its icon | 100 %, 23.9 % |
| `maxRank` | number | Best rank reached | 51.7 % |
| `isPinned` | boolean | The pinned top entry (置顶) | 100 % |
| `coverUrl` | string | Topic cover | 99.5 % |
| `searchUrl`, `hotspotUrl` | string | Douyin search and hot-spot pages for the topic | 100 % |

#### CSV columns (videos)

`awemeId, url, mediaType, desc, title, createTime, createTimeUnix, hashtags/0…, mentions/0/…, diggCount, commentCount, shareCount, collectCount, durationSec, width, height, coverUrl, dynamicCoverUrl, videoUrl, images/0…, imageCount, musicId, musicTitle, musicAuthor, musicIsOriginal, musicDurationSec, musicCoverUrl, authorUid, authorSecUid, authorUniqueId, authorNickname, authorUrl, authorAvatarUrl, authorSignature, authorVerification, authorFollowers, authorFollowing, authorTotalLikes, authorVideoCount, authorIpLocation, authorRegion, postCityCode, postProvince, shareUrl, keyword, searchTab, rank, scrapedAt`

***

### Real output sample

Real rows from platform runs of the final build (unmasked — this is what Douyin shows publicly). Long URLs are shortened with `…` here only.

**Video — Search videos mode (keyword 红烧肉, run of 25 October 2026)**

```json
{"awemeId": "7672709256164634612", "url": "https://www.douyin.com/video/7672709256164634612", "mediaType": "video", "desc": "百吃不厌的红烧肉🔥 色泽红亮，肥而不腻，软烂入味 家里做，简单零难度，妥妥的下饭硬菜 #红烧肉 #家常菜教程 #下饭菜 #美食教程 #跟着抖音学做菜@抖音美食达人助手 @抖音小助手", "title": null, "createTime": "2026-08-11T09:50:35.000Z", "createTimeUnix": 1786441835, "hashtags": ["红烧肉", "家常菜教程", "下饭菜", "美食教程", "跟着抖音学做菜"], "mentions": [{"secUid": "MS4wLjABAAAA5hb4mLGLnHl26-u6hBzUSYsImt09ZvB8hV4_KxPWGVM", "nickname": "抖音美食达人助手", "url": "https://www.douyin.com/user/MS4wLjABAAAA5hb4mLGLnHl26-u6hBzU…"}, {"secUid": "MS4wLjABAAAAGA9bHrExvrQmowuVfRZxjG4s07M7EUjf1PlaHRHqdls", "nickname": "抖音小助手", "url": "https://www.douyin.com/user/MS4wLjABAAAAGA9bHrExvrQmowuVfRZx…"}], "diggCount": 6988, "commentCount": 383, "shareCount": 2547, "collectCount": 9820, "durationSec": 68.9, "width": 1080, "height": 1920, "coverUrl": "https://p26-sign.douyinpic.com/tos-cn-p-0015/oE9AACEdGIDT7TA…", "dynamicCoverUrl": "https://p26-sign.douyinpic.com/obj/tos-cn-i-0813c001/o81ANi6…", "videoUrl": "https://v3-dymsearch.douyinvod.com/c0fb462ea5aa2a96a57d051b3…", "images": [], "imageCount": null, "musicId": "7672709239776889650", "musicTitle": "@阿伟的厨房创作的原声", "musicAuthor": "阿伟的厨房", "musicIsOriginal": false, "musicDurationSec": 68, "musicCoverUrl": "https://p3.douyinpic.com/aweme/720x720/aweme-avatar/tos-cn-i…", "authorUid": "1395705427565376", "authorSecUid": "MS4wLjABAAAAHCeFjetQT1X704oD6kxSyWDVc5o67FUvQ4T2RlBNg_g5IUW7D7IqpwkeBJXHHkci", "authorUniqueId": "65929546401", "authorNickname": "阿伟的厨房", "authorUrl": "https://www.douyin.com/user/MS4wLjABAAAAHCeFjetQT1X704oD6kxS…", "authorAvatarUrl": "https://p3.douyinpic.com/aweme/100x100/aweme-avatar/tos-cn-i…", "authorSignature": "干厨师整整20年，深耕后厨\n每天一道下饭家常菜\n手把手教你做菜，用料简单\n爱吃、会吃、更会做～\n谢谢你的喜欢和关注~🥰", "authorVerification": null, "authorFollowers": 65478, "authorFollowing": 0, "authorTotalLikes": 248129, "authorVideoCount": 125, "authorIpLocation": "河南", "authorRegion": "CN", "postCityCode": "410900", "postProvince": "河南省", "shareUrl": "https://www.iesdouyin.com/share/video/7672709256164634612/?r…", "keyword": "红烧肉", "searchTab": "general", "rank": 1, "scrapedAt": "2026-10-24T23:10:17.359Z"}
```

Image posts (图文) have the same columns with `mediaType: "images"`, the image URLs in `images`, `imageCount`, and no `videoUrl` / `durationSec`.

**User — Search users mode (keyword 健身)**

```json
{"uid": "3703570636486996", "secUid": "MS4wLjABAAAAsXNghwdTOenKchYb-LdYmoB5ouq9WB1AYKyDyIZGmQ-QrJUZJPxHEgOI32plz-hI", "uniqueId": "98598236022", "nickname": "健身华哥", "url": "https://www.douyin.com/user/MS4wLjABAAAAsXNghwdTOenKchYb-LdY…", "followers": 7221765, "following": 569, "totalLikes": 100056361, "videoCount": 342, "likedVideosCount": 0, "signature": "国家级裁判员\n航空兵第十师退役\n百日彭于晏招募中\n百人百日百万华哥带你练\n选手报名📮：huage9231@163.com\n教官招募📮：huage9117@163.com\n以行动传递全民健身理念 一起加油💪\n商务V:Zxdtydf1(添加请备注）", "ipLocation": "上海", "age": null, "verification": null, "enterpriseVerification": null, "isLive": false, "roomId": null, "mixCount": 10, "isPrivate": false, "avatarUrl": "https://p3.douyinpic.com/aweme/1080x1080/aweme-avatar/tos-cn…", "keyword": "健身", "rank": 1, "scrapedAt": "2026-10-24T23:10:41.966Z"}
```

**Comment — Comments mode**

```json
{"commentId": "7699802585058132755", "awemeId": "7690795980844846371", "videoUrl": "https://www.douyin.com/video/7690795980844846371", "text": "鸡蛋可以做成那种拉丝蛋吗，感觉会更好吃", "createTime": "2026-10-23T10:06:34.000Z", "diggCount": 1, "replyCount": 1, "ipLocation": "海南", "isHot": false, "isAuthorLiked": false, "label": null, "imageUrls": [], "userUid": "3876203527947594", "userSecUid": "MS4wLjABAAAAYImurRJnwmI5xUd_rAseQb7XjlUXcIDnMrnxQ8g62MMhCiMGwoVONkZbh_xzdbKG", "userUniqueId": "40834977101", "userNickname": "后天", "userUrl": "https://www.douyin.com/user/MS4wLjABAAAAYImurRJnwmI5xUd_rAse…", "userAvatarUrl": "https://p3.douyinpic.com/aweme/100x100/aweme-avatar/tos-cn-i…", "userRegion": "CN", "rank": 1, "scrapedAt": "2026-10-24T23:11:21.846Z"}
```

**Hot-search entry — Hot search mode**

```json
{"board": "hot", "rank": null, "word": "渡船之上 信仰如磐", "hotValue": null, "videoCount": null, "viewCount": null, "eventTime": null, "sentenceId": "2711825", "groupId": null, "labelCode": 0, "labelIconUrl": null, "maxRank": null, "isPinned": true, "coverUrl": null, "searchUrl": "https://www.douyin.com/search/%E6%B8%A1%E8%88%B9%E4%B9%8B%E4…", "hotspotUrl": "https://www.douyin.com/hot/2711825", "scrapedAt": "2026-10-24T23:11:45.057Z"}
```

***

### How the access works

Douyin's desktop site (www.douyin.com) asks visitors who are not logged in to log in before searching (`status_code 2483`, "请先登录，再继续搜索吧"), and it protects a creator's video list and single-video pages with a visitor id that only a real browser receives. Douyin's **mobile search site** — so.douyin.com, the search Douyin serves to phone browsers — answers the same searches to anyone. This Actor reads that site the way a phone browser does: one server-rendered search page per keyword (which carries the first results and the search session), then the site's own JSON pages for the video tab, the general tab and the users tab. Video details come from the same site's multi-video endpoint (20 videos per request), comments from its comment list. Creator profiles and the hot-search boards come from www.douyin.com's web API, signed the way Douyin's own page signs it, with a guest token.

Routes: the Actor starts on Apify's direct connection (fastest; measured search pages in 0.7–2 s) and moves to Apify's datacenter proxies when Douyin refuses an exit, keeping track per Douyin site (the profile API and the search site rate-limit independently). Residential proxies are only a rescue for small runs. You do not need to configure anything.

What happens when Douyin pushes back: a verification page or an empty answer retires that session and the next request uses a fresh one; three refusals in a row rest the route; HTTP 429/503 slow the pace down instead. Every request has a hard time limit, and the run keeps a time reserve so it always ends cleanly and writes its `SUMMARY`.

***

### Scale and speed (measured 25 October 2026)

| Run | Input | Result | Time |
|---|---|---|---|
| Quick sample (the default prefill) | 美食, 20 results | 20 videos | 10.7 s end to end, first rows after ~5 s |
| 1,000 videos | 10 keywords, default settings (author profiles on) | 1,000 unique videos | 54.8 s |
| **10,000+ videos** | **110 keywords, default settings** | **10,346 unique videos, 0 duplicates, 9,434 author profiles** | **1,008 s (16 min 48 s)** |
| Related-keyword expansion | 露营 + 5 related keywords | 400 videos | 21 s |
| Users | 健身, 美食, 旅行 | 205 users with profiles | 87 s |
| Comments | 3 videos × 200 | 600 comments | 10 s |
| Hot search | 4 boards | 201 entries | 4 s |
| Video details | 4 links (one short link) | 4 videos | 6.7 s |

**How many videos does one keyword give?** Whatever Douyin's search shows for it: in the 110-keyword run each keyword added between 27 and 295 videos that earlier keywords had not already found (median 84; 美食 253, 发型 295, 理财 240, 游戏 223; 烘焙 27, 健康 36). Douyin ends a search with "no more results" after roughly 10 pages per tab — there is no hidden extra depth to unlock, so **big datasets come from many keywords**: write a keyword list or turn on related keywords. 719 videos in that run were found by more than one keyword and were saved once.

**What the 10,346 videos looked like:** 7,971 videos and 2,375 image posts; 68 % from the video tab, 32 % from the general tab; 9,434 different creators; 7,043 published in 2026, 1,771 in 2025, older ones back to 2018; median 1,481 likes (top video: 25,390,817); most posts from 广东省 (1,406), 浙江省 (744), 河南省 (680), 山东省 (666) and 四川省 (587).

**Throughput:** about 10 videos per second with author profiles (measured over the 16-minute run). Estimated from that rate, the default run timeout of 1 hour holds roughly 30,000 videos, and 100,000 videos need about 3 hours and on the order of 1,000 keywords — raise the run timeout for pulls that big.

***

### Data quality: how the rows were checked

- **Hand check against douyin.com.** Eleven videos from the 10,346-row run and one creator profile were opened in a normal browser on www.douyin.com. Likes, comments, saves and shares matched the page (the page rounds: 21.3万 = 212,491), publish times matched to the second (the page shows Beijing time), captions, author names, Douyin IDs, follower counts and IP locations matched. One comment count was 2 lower on the page than in the row — two comments had been removed in between.
- **Two fixes came out of it** and are in version 1.0: the follower number now is the one the profile page shows (粉丝, counted across Douyin's apps — 2327.7万 for the checked creator, where Douyin's older main-app field says 2291万), and verification labels now include the certification text (认证, e.g. 美食自媒体、中国药膳大师).
- **Uniqueness.** An independent pass over the 10,346-row dataset found 10,346 distinct `awemeId` values, no empty ids, and consistent types in every column.
- **No placeholders.** Live-room and shop cards that sit between search results (19 in the big run) are skipped instead of being written as half-empty videos; play counts, which Douyin's web data reports as 0 for everyone, are not offered as a column at all.

***

### What you pay

Pay per result (one dataset row = one result). Store tier discounts apply automatically:

| Tier | FREE | BRONZE | SILVER | GOLD | PLATINUM | DIAMOND |
|---|---|---|---|---|---|---|
| Per 1,000 results | $3.50 | $3.10 | $2.70 | $2.30 | $2.30 | $2.30 |

| Pull | Rows | Free | Bronze | Silver | Gold and above |
|---|---|---|---|---|---|
| Sample | 1,000 | $3.50 | $3.10 | $2.70 | $2.30 |
| Dataset | 10,000 | $35 | $31 | $27 | $23 |
| Large dataset | 100,000 | $350 | $310 | $270 | $230 |

The price is per saved row whatever the mode (videos, users, comments, profiles, hot-search entries); the author profiles that enrich video rows, retries and duplicates that are skipped are not charged.

#### Maximum cost per run

Every run has a **Maximum cost per run** (set in the run options, or `maxTotalChargeUsd` in the API). The Actor turns it into a row budget at your price and stops cleanly when it is reached — it never writes a row it cannot charge for, and the status message says how many rows the budget covered. Measured: a run with a $0.05 cap saved exactly the 16 rows that $0.05 covered and finished as SUCCEEDED, with 16 charged results. Rule of thumb on the Free tier: $3.50 covers 1,000 rows, $35 covers 10,000.

***

### Integrations

- **Google Sheets** — use Apify's Google Sheets integration on the run, or `IMPORTDATA` the dataset's CSV URL.
- **Make, Zapier, n8n** — "Run Actor" with an input from the [Cookbook](#cookbook-16-ready-to-run-inputs), then "Get dataset items".
- **Airtable** — map `awemeId` (or `secUid` for users) as the primary field to upsert.
- **Webhooks** — add a webhook on *Run succeeded* that receives the dataset id; fetch the items as JSON or CSV.
- **Schedules** — hourly hot search, daily brand search, weekly creator list refreshes.
- **Data warehouses** — load the JSON or CSV export into BigQuery, Snowflake, Redshift, ClickHouse or Postgres; `awemeId`, `secUid` and `commentId` are stable keys across runs.
- **AI agents and MCP** — the Actor is available to MCP clients (Claude, ChatGPT connectors, Cursor …) through Apify's MCP server; an agent can call it with a keyword and read the rows.
- **API clients** — `apify-client` for Node.js and Python, or plain HTTP (see the [API tutorial](#tutorial-scrape-douyin-with-the-api)).

***

### Performance tips

- **More keywords beat bigger numbers.** One keyword gives what Douyin's search shows (tens to a few hundred videos). Use a keyword list or `expandRelatedKeywords` for thousands.
- **Turn off author profiles when you do not need follower numbers.** `includeAuthorProfiles: false` skips one profile request per new creator.
- **Use `maxItemsPerKeyword`** to keep a long keyword list balanced instead of letting the first keywords fill the run.
- **Re-check known videos with Video details mode** — 20 videos per request, much faster than searching again.
- **Schedule small runs** instead of one huge run when you need freshness (hot search hourly, brand search daily).
- **Leave the proxy setting empty.** The Actor's own route choice is faster than forcing a proxy (measured: search via the datacenter pool is 2–4× slower than the direct connection).

***

### Troubleshooting: every status message explained

| Status message (start) | Run status | What it means | What to do |
|---|---|---|---|
| `Done: saved N videos (all results read) …` | Succeeded | Every keyword or URL was read to the end | — |
| `Done: saved N videos (max results reached) …` | Succeeded | `maxItems` reached | Raise `maxItems` or set 0 |
| `Done: … (stopped at the run time limit)` | Succeeded | The run's timeout came first; rows so far are saved | Raise the run timeout |
| `Partly done: … N keywords could not be searched …` | Succeeded | Douyin refused some keywords' search pages on every route for a while | Re-run those keywords later |
| `… N inputs not found` / `N inputs could not be read` | Succeeded | Deleted, private or invalid links/ids; unreadable inputs are listed in `SUMMARY.notes` | Check the links |
| `… N author profiles could not be read (those rows have no follower numbers)` | Succeeded | Douyin refused some profile requests; the video rows are complete except the profile fields | Re-run if you need them |
| `Saved N … this run's maximum cost ($X) covers N results …` | Succeeded | The maximum cost per run was reached | Raise "Maximum cost per run" |
| `No videos found — Douyin answered every request but returned 0 results …` | Succeeded | Nothing matched (common for non-existent ids) | Check inputs or use other keywords |
| `Nothing to scrape: mode "…" needs …` | Failed | The input lacks keywords or URLs for the chosen mode | Fill the field the message names |
| `Unknown mode …` | Failed | `mode` is not one of the six | Use `search`, `users`, `videos`, `comments`, `profiles` or `trending` |
| `No … collected: Douyin refused every route this run tried …` | Failed | A temporary access refusal — not an empty result | Run again in a few minutes |
| `No … collected: Douyin could not be reached …` | Failed | Network failure (often a broken custom proxy) | Clear the proxy setting, run again |
| `The run time limit was reached before any result could be collected.` | Failed | Timeout too short | Use at least 60 s |

The `SUMMARY` record (default key-value store) has the outcome (`COMPLETED`, `PARTIAL`, `EMPTY_RESULT`, `BLOCKED`, `FETCH_FAILED`, `INVALID_INPUT`), per-keyword results, requests by route and every note.

***

### Honest limits

- **Search depth is Douyin's.** A keyword returns what Douyin's search shows (in the big run 27–295 new videos per keyword, about 10 pages per tab); there is no way to page further. Use more keywords.
- **No sorting or date filters for search.** Douyin's mobile search does not offer guests its sort/date filters; results come in Douyin's relevance order. Sort and filter the dataset afterwards (`createTime`, `diggCount`).
- **A creator's full video list is not available.** Douyin shows a profile's video list only to logged-in users (and refuses guests after the first page), so this Actor offers the profile's numbers (video count, likes, followers) but not "every video of a creator". Searching the creator's name or Douyin ID returns their videos that Douyin's search ranks.
- **Hashtag (话题) video lists and follower lists** are also login-only on Douyin and are not offered.
- **Play/view counts of single videos are not offered** — Douyin's web data reports them as 0 for everyone.
- **Comment replies** (楼中楼) are not collected; `replyCount` says how many each comment has. Comments come in Douyin's own default order — its hot ranking, which puts popular comments (`isHot`) first and mixes in recent ones; sort by `diggCount` or `createTime` afterwards if you need a strict order.
- **Video and image URLs are signed links** that expire after some hours; download media soon after the run if you need it.
- **Private, deleted and region-restricted posts** are not returned (Video details reports them as not found).
- **Douyin changes.** When Douyin changes its site the Actor is updated; the `SUMMARY` and status messages always say when something could not be read.

***

### Comparison: Douyin Open Platform, manual copying and this Actor

| | Douyin Open Platform (开放平台) | Manual copying | This Actor |
|---|---|---|---|
| Access | Registered developer app, review, and each user's authorization; data mainly about the authorizing account | Phone or browser, one video at a time | None — public data, no account |
| Keyword search across Douyin | Not for third parties | Yes, by hand | Yes, video and user search |
| Other creators' public numbers | Limited | By hand | Followers, likes, video count, IP location, verification |
| Comments | For your own content | By hand | Any public video |
| Volume | Rate-limited per app | Dozens per hour | 10,000+ rows per run (measured) |
| Output | JSON via API | Notes | JSON, CSV, Excel, API, integrations |
| Cost | Free but gated | Labour | $2.30–$3.50 per 1,000 rows |

Generic web scrapers fail on Douyin because the desktop site requires login for search and protects its data with signatures and visitor ids; this Actor uses the public mobile search and signs the remaining calls the way Douyin's own page does.

***

### FAQ

#### What is a Douyin scraper?

A tool that collects public Douyin data — videos, creators, comments, trending topics — into structured rows. This one does it without a login and exports to CSV, Excel or JSON.

#### Is this a Douyin API alternative?

Yes. It gives keyword search, video details, comments, profiles and hot search as data rows, without an Open Platform app, API key or user authorization.

#### How do I scrape Douyin without logging in?

Start this Actor with a keyword. It reads Douyin's public mobile search (so.douyin.com) and public web data — nothing behind a login.

#### Can I search Douyin videos by keyword?

Yes — that is the default mode. Each keyword returns the videos Douyin's search shows on its video and general tabs, de-duplicated.

#### How many videos can I get from Douyin?

As many as your keywords cover: measured 10,346 unique videos from 110 keywords in one run (16 min 48 s). One keyword typically gives tens to a few hundred.

#### Why does one keyword stop after ~100 videos?

Douyin's search ends there ("no more results" after about 10 pages per tab). Add keywords or turn on related keywords to go wider.

#### Do Chinese or English keywords work better?

Chinese. Douyin is a Chinese platform; English keywords only match posts that use English words (brands, product names).

#### Can I scrape Douyin comments?

Yes, with Comments mode: paste video links or ids; each comment comes with text, likes, reply count, time, the commenter and their IP province, in Douyin's own (hot) order.

#### Can I get the replies to comments?

Not individually — each comment row has `replyCount`. Top-level comments only.

#### Can I scrape Douyin user profiles?

Yes, with Profiles mode: profile links, sec_uid values or Douyin IDs (抖音号). You get followers, following, total likes, video count, bio, IP location, verification and more.

#### How do I find Douyin influencers (达人) for a niche?

Use Search users with niche keywords and the follower-range filter (e.g. 10w–100w); profiles are included by default.

#### Can I get all videos of one Douyin account?

No — Douyin shows a creator's video list only to logged-in users. The Actor gives the account's statistics; searching the creator's name returns their videos that rank in search.

#### Does it show the follower count I see on Douyin?

Yes. `followers` / `authorFollowers` is the 粉丝 number on the profile page (Douyin counts followers across its apps there).

#### Why are play counts missing?

Douyin's web data reports 0 plays for every video, so the column is not offered rather than filled with fake zeros.

#### Can I download Douyin videos?

Each video row has `videoUrl`, a playable MP4 link (it expires after some hours). The Actor itself saves metadata, not video files.

#### Does it get Douyin image posts (图文)?

Yes: `mediaType: "images"`, with every image URL in `images` and the count in `imageCount`.

#### What is a sec_uid?

Douyin's public profile key (`MS4wLjABAAAA…`), part of every profile URL. The Actor returns it for every author and accepts it as input.

#### What is the difference between uid, sec_uid and Douyin ID (抖音号)?

`uid` is the internal numeric id, `sec_uid` the public profile key in URLs, and the Douyin ID (`uniqueId`) the handle users choose and search for.

#### Can I paste v.douyin.com share links?

Yes — short links and whole share texts ("复制打开抖音… https://v.douyin.com/…") work in Video details, Comments and Profiles.

#### Can I export Douyin data to Excel or CSV?

Yes, from the Output tab or the dataset API (`format=csv` or `xlsx`).

#### Can I scrape the Douyin hot search list (抖音热榜)?

Yes, Hot search mode: the main board plus the entertainment, society and challenge boards, about 50 entries each, with heat values.

#### How often can I scrape the hot search?

As often as you like — a run takes about 4 seconds. Hourly schedules are common.

#### Do I need proxies?

No. Leave the proxy setting empty; the Actor chooses its route.

#### How much does it cost to scrape 10,000 Douyin videos?

$35 on the Free tier, $23 on Gold and above — the price is per saved row.

#### Will I get duplicates?

No. Every video, user, comment and profile is saved once per run (by Douyin's own id), even when several keywords find it.

#### Does it work for TikTok?

No — Douyin and TikTok are separate platforms with separate data.

#### Can I filter search by date or sort by likes?

Not on Douyin's side (guests get relevance order). Filter and sort the dataset — `createTime`, `diggCount` and friends are numbers and ISO dates.

#### Where does the province come from?

Douyin tags each post with the six-digit administrative code of the city it was published from (`postCityCode`); `postProvince` is that code's province. The creator's own IP location (`authorIpLocation`) is shown separately.

#### Can AI agents use this Douyin scraper?

Yes, through Apify's API and MCP server — an agent can run a keyword search and read the rows.

#### What happens if Douyin blocks a run?

The Actor switches sessions and routes by itself; if Douyin refuses everything for a while, the run fails with a clear message instead of pretending the result is empty.

#### 抖音数据怎么导出到Excel？(How do I export Douyin data to Excel?)

在本 Actor 中输入关键词（如“美食”），运行结束后在 Output 标签页点击 Export，选择 Excel 或 CSV 即可。无需登录抖音账号。

#### 抖音评论可以批量采集吗？(Can Douyin comments be collected in bulk?)

可以。选择 Comments 模式，粘贴多个视频链接，设置每个视频的评论数量即可批量导出评论内容、点赞数和IP属地。

***

### Glossary

| Term | Meaning |
|---|---|
| 抖音 (Douyin) | ByteDance's Chinese short-video platform (the Chinese counterpart of TikTok) |
| 作品 (aweme) | A post — video or image post; `awemeId` is its id |
| 图文 | Image post (a carousel of photos with music) — `mediaType: "images"` |
| 点赞 | Like — `diggCount` |
| 评论 | Comment — `commentCount`, Comments mode |
| 分享 / 转发 | Share — `shareCount` |
| 收藏 | Save / favourite — `collectCount` |
| 粉丝 | Followers — `followers`, `authorFollowers` |
| 关注 | Following — `following` |
| 获赞 | Total likes received — `totalLikes` |
| 抖音号 | Douyin ID, the handle — `uniqueId` |
| sec_uid | Public profile key in URLs (`MS4wLjABAAAA…`) |
| IP属地 | IP location Douyin shows on profiles and comments |
| 认证 / 企业认证 / 个人认证 | Verification / verified business / verified individual |
| 达人 / KOL | Creator / influencer |
| 话题 (#) | Hashtag |
| 热榜 | Hot search board; 娱乐榜 entertainment, 社会榜 society, 挑战榜 challenges |
| 热度 | Heat value of a hot-search topic — `hotValue` |
| 相关搜索 | Related searches Douyin suggests — `expandRelatedKeywords` |
| 综合 / 视频 / 用户 | Douyin search tabs: general / video / users |
| 原声 | Original sound — `musicIsOriginal` |
| 合集 | Collection (series) of posts — `mixCount` |
| 直播 | Live stream — `isLive`, `roomId` |

***

### Is it legal to scrape Douyin?

This Actor collects only information that Douyin publishes to every visitor without a login: public videos, public profiles, public comments and the public hot-search boards. Collecting publicly available data is generally lawful in many jurisdictions, but **how you use it is your responsibility**. Much of this data is about people (names, handles, bios, IP provinces, comments). If you store or process it, apply the law that governs you and your data subjects — China's **Personal Information Protection Law (PIPL)**, the EU/UK **GDPR**, and others — including purpose limitation, data minimisation and deletion on request. Respect Douyin's terms where they apply to you, do not republish content in ways that infringe creators' copyright, and do not use the data for harassment, spam or discrimination. If in doubt, ask a lawyer about your specific use.

***

### Changelog

- **1.0 (25 October 2026)** — First release. Six modes (search videos, search users, video details, comments, profiles, hot search); author profile enrichment with the follower number shown on Douyin; related-keyword expansion; route ladder (direct → datacenter → residential rescue) per Douyin site; outcome-aware status messages and `SUMMARY`; maximum-cost-per-run support. Measured 10,346 unique videos in one run.

***

### Support

Questions, a missing field or a mode you need? Open an issue on the Actor's **Issues** tab — we reply within 24 hours. Please include the run id; the `SUMMARY` record of the run usually tells us what happened.

# Changelog

This Actor's version history is a separate document: https://apify.com/logiover/douyin-scraper/changelog.md

# Actor input Schema

## `mode` (type: `string`):

<b>Search videos</b> — videos for each keyword (Douyin's video tab and general tab). <b>Search users</b> — creator accounts for each keyword. <b>Video details</b> — one row per video URL / id. <b>Comments</b> — the comments of each video URL / id. <b>Profiles</b> — one row per profile URL, sec_uid or Douyin ID (抖音号). <b>Hot search</b> — Douyin's trending boards (抖音热榜).

## `keywords` (type: `array`):

For "Search videos" and "Search users". One keyword per line. Chinese keywords (美食, 旅行, 健身 …) match far more content than English ones. Each keyword returns what Douyin's search shows for it (typically 60–300 videos); add more keywords — or turn on "Add related keywords" — for bigger datasets.

## `urls` (type: `array`):

For "Video details" and "Comments": video links (https://www.douyin.com/video/…, /note/…, v.douyin.com short links, share links) or bare video ids. For "Profiles": profile links (https://www.douyin.com/user/…), sec_uid values (MS4wLjABAAAA…), v.douyin.com profile short links or Douyin IDs (抖音号).

## `maxItems` (type: `integer`):

Stop after this many rows in total (videos, users, comments …). 0 = no limit (the run stops when every keyword or URL is read, or at the run's maximum cost).

## `maxItemsPerKeyword` (type: `integer`):

Cap for each keyword, so a long keyword list is spread evenly. 0 = everything Douyin returns for the keyword.

## `searchTabs` (type: `string`):

Which of Douyin's search tabs to read for each keyword. Both tabs together return the most unique videos (duplicates are removed).

## `expandRelatedKeywords` (type: `boolean`):

Also search the related keywords Douyin suggests under the results (相关搜索), up to the limit below. Turns a few seed keywords into thousands of videos on the same topic.

## `maxRelatedKeywords` (type: `integer`):

How many related keywords may be added in total when "Add related keywords" is on.

## `includeAuthorProfiles` (type: `boolean`):

Douyin hides follower and like counts inside search results. With this on, each author's profile is read once (cached) and the row gets followers, following, total likes, video count, signature and IP location (IP属地). Turn off for the fastest possible run.

## `userFollowers` (type: `string`):

Only for "Search users": Douyin's own follower filter (粉丝数量).

## `userType` (type: `string`):

Only for "Search users": Douyin's own account-type filter (用户类型).

## `maxCommentsPerVideo` (type: `integer`):

Only for "Comments": how many top-level comments to read for each video, in Douyin's own default order (its hot ranking: popular comments first, mixed with recent ones).

## `trendingBoards` (type: `array`):

Only for "Hot search": which of Douyin's boards to export (about 50 entries each).

## `proxyConfiguration` (type: `object`):

Leave as is: the Actor chooses the route itself (direct connection first, then Apify datacenter and, for small runs, residential IPs when Douyin refuses one). Set a proxy only if you want every request to go through it.

## Actor input object example

```json
{
  "mode": "search",
  "keywords": [
    "美食"
  ],
  "urls": [],
  "maxItems": 20,
  "maxItemsPerKeyword": 0,
  "searchTabs": "all",
  "expandRelatedKeywords": false,
  "maxRelatedKeywords": 30,
  "includeAuthorProfiles": true,
  "userFollowers": "",
  "userType": "",
  "maxCommentsPerVideo": 100,
  "trendingBoards": [
    "hot"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

All rows collected in this run.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "keywords": [
        "美食"
    ],
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("logiover/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "keywords": ["美食"],
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("logiover/douyin-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "keywords": [
    "美食"
  ],
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call logiover/douyin-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,logiover/douyin-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hMAt4CsGePWxicv3N/builds/cSokE8L1nVPyQIBOL/openapi.json