# Douyin 抖音 Scraper - Videos, Comments, Profiles & Hot Search (`clover_folktale/douyin-scraper`) Actor

Scrape Douyin (抖音, the Chinese TikTok): video search, creator (博主) videos and profiles, comments, followers, hashtag and sound feeds, and the hot search board (热榜). Video authors and commenters come with user ID, sec_uid and IP location. No login or cookies needed. Export to JSON, CSV or Excel.

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

## Pricing

from $5.00 / 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 collects public data from **Douyin** (抖音, the Chinese version of TikTok) and returns clean, flat JSON. It covers the live hot search board (热榜), video search, a creator's (博主) videos, video details, creator profiles, public comments, hashtag feeds, follower and following lists, creator search, videos by sound, and the hot video, topic and city boards. The public profile of every user is included: user IDs, avatar, IP location (IP属地), gender and bio. No proxies, cookies, login or Chinese phone number needed. You can also use it as a Douyin API: call it over HTTP or with the Apify Python or JavaScript client and get the same JSON back.

### What is Douyin?

Douyin (抖音) is the Chinese short-video app and the Chinese counterpart of TikTok. It runs separately from TikTok, with its own accounts, videos and trends. Creators post short videos with hashtags and sounds, viewers comment and like, and the app shows a hot search board of trending topics.

### What data can you get?

#### Modes

Each run uses one mode. The `type` field of every item tells you which kind of record it is.

| Mode | Give it | Record `type` | You get |
|---|---|---|---|
| `hot` | nothing | `hotTopic` | The current Douyin hot search board: rank, topic, heat value, view and video counts, search link |
| `search` | a keyword | `video` | Videos matching the keyword, with engagement counts, hashtags, music, author data, cover and video links |
| `creator` | profile URLs, share links or `sec_uid`s | `video` | A creator's videos, newest first, in the same format as search |
| `video` | video URLs, share links or video IDs | `videoDetail` | Full details of each video (same fields, one lookup per video) |
| `profile` | profile URLs, share links or `sec_uid`s | `profile` | Nickname, user IDs, avatar, gender, IP location, country/province/city, bio, followers, following, total likes received, video count, verification text |
| `comments` | video URLs, share links or video IDs | `comment` | Comment text, likes, reply count, time, plus each commenter's public profile |
| `hashtag` | hashtag IDs or hashtag URLs | `video` | The videos posted under a hashtag |
| `followers` | profile URLs, share links or `sec_uid`s | `follower` | The accounts that follow a creator, each with its public profile |
| `following` | profile URLs, share links or `sec_uid`s | `following` | The accounts a creator follows, same fields as `followers` |
| `users` | a keyword | `user` | Creator search: matching accounts with nickname, avatar, followers, likes received, video count and category |
| `music` | sound URLs or sound IDs | `video` | The videos that use a sound, in the same format as search |
| `board` | a board name (optional keyword, time window, city) | `boardVideo`, `boardTopic`, `boardHotspot` | The extended boards: `videos` (hot video board), `topics` (hot hashtags), `risingTopics` (hashtags rising fastest), `rising` (rising hot spots) and `city` (hot spots of one city) with rank and heat, plus a heat history for topics and hot spots |

#### Videos (`video`, `videoDetail`)

| Field | Description |
|---|---|
| `awemeId` | Douyin video ID |
| `url` | Link to the video page |
| `description` | Video caption as published |
| `createdAt` | Publish time |
| `likeCount`, `commentCount`, `shareCount`, `collectCount` | Likes, comments, shares and saves |
| `durationSeconds` | Video length in seconds |
| `hashtags` | Hashtags in the caption |
| `musicId`, `musicTitle`, `musicAuthor` | The sound used; pass `musicId` to mode `music` |
| `authorUid` | Author's numeric Douyin user ID |
| `authorSecUid` | Author's sec_uid |
| `authorDouyinId` | Author's custom Douyin ID |
| `authorNickname` | Author's nickname |
| `authorIpLocation` | Author's IP location (province or country) shown on the video |
| `authorRegion` | Author's country or region code, e.g. CN |
| `authorGender` | male or female; null when not shown |
| `authorBio` | Author's bio as published |
| `authorFollowerCount` | Author's follower count |
| `authorVerified` | Author's verification text |
| `authorAvatar` | Author's avatar image URL (largest available) |
| `coverUrl`, `videoUrl` | Cover image and video file links (temporary CDN links) |

#### Comments (`comment`)

| Field | Description |
|---|---|
| `text` | Comment text |
| `commentId` | Comment ID |
| `awemeId` | ID of the video the comment belongs to |
| `likeCount`, `replyCount` | Likes and number of replies |
| `createdAt` | Comment time |
| `isPinned` | Whether the comment is pinned |
| `nickname` | Commenter's nickname |
| `userId` | Commenter's numeric Douyin user ID |
| `userSecUid` | Commenter's sec_uid |
| `userDouyinId` | Commenter's custom Douyin ID when set |
| `userIpLocation` | Commenter's IP location (province or country) shown under the comment |
| `userAvatar` | Commenter's avatar image URL |
| `userVerified` | Commenter's verification text |

#### Profiles, followers and following (`profile`, `follower`, `following`)

| Field | Description |
|---|---|
| `nickname` | Account nickname |
| `uid` | Numeric Douyin user ID |
| `secUid` | The account's sec_uid |
| `douyinId` | Custom Douyin ID |
| `followerCount`, `followingCount` | Followers and accounts followed |
| `likedCount` | Total likes received |
| `videoCount` | Number of videos |
| `ipLocation` | IP location shown on the profile, without the label prefix |
| `country`, `province`, `city` | Location shown on the profile |
| `gender` | male or female; null when not shown |
| `bio` | Bio as published |
| `verified` | Verification text |
| `avatarUrl` | Avatar image URL (largest available) |
| `url` | Link to the profile |
| `ownerSecUid` | Only on `follower` / `following`: the creator whose list it is |

#### Creator search (`user`)

Creator search entries carry `secUid`, `nickname`, `avatarUrl`, `followerCount`, `likedCount`, `videoCount`, `category` (the category tag Douyin gives the account) and `url`.

#### Hot search board (`hotTopic`)

Hot topics carry `rank`, `word` (the topic), `hotValue` (heat value), `viewCount`, `videoCount`, `sentenceId` and `url` (search link).

#### Extended boards (`boardVideo`, `boardTopic`, `boardHotspot`)

All board entries carry `board` (which board: `videos`, `topics`, `risingTopics`, `rising` or `city`), `rank` and `createdAt` (publish or creation time).

- `boardVideo` adds `awemeId`, `description`, `playCount` (plays), `likeCount`, `likeRate` (likes per play), `followerGain` (followers the video brought in), `followRate` (followers gained per play), `score` (board heat score), `authorNickname`, `authorAvatar`, `authorFollowerCount`, `coverUrl` and `url`. It has no heat history.
- `boardTopic` adds `challengeId` (hashtag ID; pass it to mode `hashtag`), `word`, `hotValue`, `viewCount`, `videoCount`, `avgViewCount` (average views per video under the topic) and a daily `trend` as `{date, value}`.
- `boardHotspot` adds `word`, `hotValue`, `rankChange` (rank movement since the previous snapshot), `videoCount`, `category` (Douyin's tag for the hot spot), `sentenceId`, `cityCode` and an hourly `trend` as `{time, hotValue}`.

### How to use Douyin Scraper

1. Open Douyin Scraper on Apify and go to the Input tab.
2. Choose a **Mode**, for example "Search videos by keyword" or "Video comments".
3. Fill the input for that mode: a keyword, creator links, video links, hashtag IDs, sound IDs or a board name.
4. Set **Max results** to the number of items you want.
5. Click Start and wait for the run to finish.
6. Open the dataset, pick a view (Videos, Comments, Creator profiles or Hot search board) and export to JSON, CSV, Excel or another format.

### Input

| Field | Type | Required | What it does | Default |
|---|---|---|---|---|
| `mode` | string | Yes | What to scrape: `hot`, `search`, `creator`, `video`, `profile`, `hashtag`, `comments`, `followers`, `following`, `users`, `music` or `board` | `hot` |
| `keyword` | string | Optional | Search keyword for modes `search` and `users`. Chinese keywords work best, e.g. "美食". In mode `board` it is an optional filter (leave empty for the full board) | `美食` |
| `creators` | array of strings | Optional | For modes `creator`, `profile`, `followers`, `following`: Douyin profile URLs (https://www.douyin.com/user/MS4w...), v.douyin.com share links or sec_uid values | none |
| `videos` | array of strings | Optional | For modes `video` and `comments`: Douyin video URLs, v.douyin.com share links or numeric video IDs | none |
| `hashtags` | array of strings | Optional | For mode `hashtag`: hashtag IDs or URLs (https://www.douyin.com/hashtag/1767587367821390) | none |
| `musics` | array of strings | Optional | For mode `music`: Douyin sound URLs (https://www.douyin.com/music/7482371896877665043) or numeric sound IDs | none |
| `board` | string | Optional | For mode `board`: `videos`, `topics`, `risingTopics`, `rising` or `city` | `videos` |
| `timeWindowHours` | integer | Optional | For the `videos`, `topics` and `risingTopics` boards: how far back to look, in hours. Allowed values: 1, 24, 72 or 168 | `24` |
| `city` | string | Optional | For the `city` board: Chinese city name (e.g. 杭州) or numeric city code. Empty reads the hot spots of all cities | none |
| `maxResults` | integer | Optional | Maximum number of items to return in total for this run (1 to 5000). You are charged per item returned | `20` |

An empty input `{}` reads the hot search board, so you can try the Actor in seconds.

Search videos by keyword:

```json
{
  "mode": "search",
  "keyword": "美食",
  "maxResults": 50
}
```

A creator's videos:

```json
{
  "mode": "creator",
  "creators": ["https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"],
  "maxResults": 40
}
```

Creator profiles:

```json
{
  "mode": "profile",
  "creators": ["https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"]
}
```

Video comments:

```json
{
  "mode": "comments",
  "videos": ["https://www.douyin.com/video/7615131515182385640"],
  "maxResults": 100
}
```

Hashtag videos:

```json
{
  "mode": "hashtag",
  "hashtags": ["https://www.douyin.com/hashtag/1767587367821390"]
}
```

A creator's followers:

```json
{
  "mode": "followers",
  "creators": ["https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"],
  "maxResults": 100
}
```

Videos using a sound:

```json
{
  "mode": "music",
  "musics": ["7482371896877665043"],
  "maxResults": 50
}
```

Hot video board for the last 24 hours:

```json
{
  "mode": "board",
  "board": "videos",
  "timeWindowHours": 24,
  "maxResults": 50
}
```

Hot spots of one city:

```json
{
  "mode": "board",
  "board": "city",
  "city": "杭州",
  "maxResults": 50
}
```

### Output example

The values below are illustrative samples.

A video (`search`, `creator`, `hashtag`, `music`; video details use `"type": "videoDetail"`):

```json
{
  "type": "video",
  "awemeId": "7615131515182385640",
  "url": "https://www.douyin.com/video/7615131515182385640",
  "description": "#红烧牛肉 家常做法，麻辣鲜香又入味 #家常菜",
  "createdAt": "2026-03-09T07:59:00Z",
  "durationSeconds": 189.6,
  "likeCount": 561,
  "commentCount": 34,
  "shareCount": 180,
  "collectCount": 380,
  "hashtags": ["红烧牛肉", "家常菜"],
  "musicId": "7482371896877665043",
  "musicTitle": "原声",
  "musicAuthor": "示例厨房",
  "authorSecUid": "MS4wLjABAAAA_example_sec_uid",
  "authorUid": "10000000001",
  "authorDouyinId": "sample_kitchen",
  "authorNickname": "示例厨房",
  "authorAvatar": "https://p3.douyinpic.com/aweme/1080x1080/aweme-avatar/example.webp",
  "authorGender": "male",
  "authorBio": "每天分享家常菜",
  "authorIpLocation": "重庆",
  "authorRegion": "CN",
  "authorFollowerCount": 125000,
  "authorVerified": null,
  "coverUrl": "https://p3.douyinpic.com/example-cover.jpeg",
  "videoUrl": "https://v3.douyinvod.com/example-video.mp4"
}
```

A comment:

```json
{
  "type": "comment",
  "commentId": "7615200000000000001",
  "awemeId": "7615131515182385640",
  "text": "看着就好吃，周末试试",
  "likeCount": 42,
  "replyCount": 3,
  "createdAt": "2026-03-09T10:15:00Z",
  "isPinned": false,
  "nickname": "示例用户",
  "userId": "10000000002",
  "userSecUid": "MS4wLjABAAAA_example_commenter",
  "userDouyinId": null,
  "userAvatar": "https://p3.douyinpic.com/aweme/100x100/example.jpeg",
  "userIpLocation": "浙江",
  "userVerified": null
}
```

A creator profile (follower and following entries use the same fields plus `ownerSecUid`):

```json
{
  "type": "profile",
  "secUid": "MS4wLjABAAAA_example_sec_uid",
  "uid": "10000000001",
  "douyinId": "sample_kitchen",
  "nickname": "示例厨房",
  "avatarUrl": "https://p3.douyinpic.com/aweme/1080x1080/aweme-avatar/example.webp",
  "gender": "male",
  "ipLocation": "重庆",
  "country": "中国",
  "province": "重庆",
  "city": null,
  "bio": "每天分享家常菜",
  "followerCount": 125000,
  "followingCount": 86,
  "likedCount": 2300000,
  "videoCount": 412,
  "verified": null,
  "url": "https://www.douyin.com/user/MS4wLjABAAAA_example_sec_uid"
}
```

A hot search topic:

```json
{
  "type": "hotTopic",
  "rank": 1,
  "word": "示例热搜话题",
  "hotValue": 11800000,
  "viewCount": 52000000,
  "videoCount": 320,
  "sentenceId": "2100000",
  "url": "https://www.douyin.com/search/示例热搜话题"
}
```

A hot topic board entry:

```json
{
  "type": "boardTopic",
  "board": "topics",
  "rank": 1,
  "challengeId": "1767587367821390",
  "word": "家常菜",
  "hotValue": 5600000,
  "viewCount": 890000000,
  "videoCount": 15000,
  "avgViewCount": 59000,
  "createdAt": "2025-11-02T00:00:00Z",
  "trend": [
    {"date": "2026-03-08", "value": 5200000},
    {"date": "2026-03-09", "value": 5600000}
  ],
  "url": "https://www.douyin.com/hashtag/1767587367821390"
}
```

### How much does it cost?

The Actor uses pay-per-event pricing: a small start fee per run plus a fee per item returned. Prices in USD:

| Event | When it is charged | Free plan | Bronze | Silver | Gold, Platinum, Diamond |
|---|---|---|---|---|---|
| `run-start` | Once per run. A video keyword search (mode `search`) is charged the start fee twice; all other modes, including creator search, once | $0.02 | $0.008 | $0.008 | $0.008 |
| `result` | Each video, comment, hot topic, follower or following entry, creator search entry or board entry returned | $0.005 | $0.005 | $0.005 | $0.005 |
| `detail` | Each full video detail (mode `video`, one lookup per video) | $0.005 | $0.0046 | $0.00415 | $0.00375 |
| `profile` | Each creator profile (mode `profile`, one lookup per creator) | $0.006 | $0.00552 | $0.005 | $0.005 |

The run-start fee is charged when the first request to the data source succeeds, even if that request returns nothing. It is not charged when the data source fails from the start or rejects the IDs, or when the spending limit cannot cover it.

You never pay for more than `maxResults` items.

Worked examples:

- 100 comments on any paid plan: $0.008 + 100 × $0.005 = $0.508, so 100 results cost about $0.51.
- 100 video details on a Gold plan: $0.008 + 100 × $0.00375 = $0.383.
- 100 creator profiles on a Silver plan: $0.008 + 100 × $0.005 = $0.508.
- 20 comments on the free plan: $0.02 + 20 × $0.005 = $0.12.

On the free Apify plan, a run returns at most 20 results in total; any paid Apify plan removes the limit. On the free Apify plan each account can run this Actor up to 3 times per 24 hours and 10 times per 7 days, within a small lifetime free allowance shared across all our Actors, and all free accounts share a daily free budget. When any of these limits is reached, the run stops before fetching anything and nothing is charged.

### Use cases

- **Trend and topic research**: read the hot search board and the topic and rising boards to see what China is searching for hour by hour, then pull the videos behind each topic.
- **Creator and influencer research**: compare creators by followers, total likes received, video count and recent video performance before a campaign or partnership.
- **Competitor and market monitoring**: follow brand hashtags, product keywords and rival accounts on a schedule.
- **Sentiment and audience analysis**: collect comments in bulk, with commenter IP location, for NLP, translation and market research.
- **Sound and content analysis**: find which videos use a given sound and how hot videos perform by plays, like rate and follower gain.
- **AI and data projects**: structured Chinese short-video data for models, dashboards and reports.

### Integrations and API

You can start runs through the Apify API, schedule them to run hourly or daily, and connect the results to Apify integrations such as webhooks, Google Sheets, Make or Zapier. Every run stores its items in a dataset that you can read over the API or export in JSON, CSV, Excel and other formats.

Example with the Python `apify-client`:

```python
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("clover_folktale/douyin-scraper").call(run_input={
    "mode": "comments",
    "videos": ["https://www.douyin.com/video/7615131515182385640"],
    "maxResults": 100,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Tips and limits

- Search returns about 8-10 videos per page and can go many pages deep.
- Douyin does not publish play counts through these lookups, so videos from search, creator, hashtag, sound and detail modes have likes, comments, shares and saves but no `playCount`. Hot video board entries (`boardVideo`) do carry `playCount`.
- Video and cover links are temporary CDN links; download what you need soon after the run.
- Hashtag mode needs the hashtag ID (the number in the hashtag page URL); names are not looked up. The `challengeId` of a topic board entry can be passed straight to mode `hashtag`.
- Every video carries its `musicId`, which you can pass to mode `music`. A sound with only a few videos returns just those videos.
- Many creators hide their followers and following list. Douyin then shows nothing, so the creator returns no results and you pay nothing for it. Each page holds about 15-20 accounts.
- Boards hold about 40-50 entries per page. For the city board use a Chinese city name (e.g. 杭州) or a city code; leave it empty for all cities.
- Invalid IDs or links are skipped; if too many inputs return nothing the run stops to protect your budget.
- Numbers such as likes and followers are what Douyin shows at the time of the run.
- On the free Apify plan a run returns at most 20 results in total.

#### Fields that are often empty

- Comment `userVerified` is filled only for verified commenters.
- Creator videos have no `authorGender`.
- Profile `city`, `province`, `country` and `gender` are empty when Douyin doesn't return them for the account.
- Follower and following entries usually have no `gender`, `ipLocation`, `city`, `province`, `country` or `verified`, and many have no bio.
- Creator search entries have only the fields listed above (no user ID or bio).
- Board videos have no author ID.

#### Privacy

Only public data is returned. Public profile data of every user is included: user IDs, avatar, IP location, gender and verification for video authors, commenters and creator profiles. Birthdays, ages and schools are not included. The bio is returned as published, including any business contact info the creator put there.

### FAQ

#### Do I need a Douyin account, cookies or proxies?

No. You don't need a login, cookies, proxies or a Chinese phone number. You only need an Apify account.

#### Is it legal to scrape Douyin?

The Actor returns only public data that Douyin shows to any visitor. It does not return private data such as private messages, birthdays, ages or schools. You are responsible for how you use the data, including compliance with privacy laws such as GDPR and with Douyin's terms.

#### How fresh is the data?

Each run reads Douyin live. Numbers such as likes and followers are what Douyin shows at the time of the run.

#### Why are some fields empty?

Douyin does not return every field for every account or video. For example, follower entries usually have no gender or IP location, creator videos have no `authorGender`, and `userVerified` is filled only for verified commenters. See "Fields that are often empty" above.

#### How many results can I get?

Up to 5000 items per run with `maxResults`. On the free Apify plan a run returns at most 20 results in total; any paid plan removes the limit. Some sources are smaller: a hidden follower list returns nothing, and a sound with few videos returns only those videos.

#### Can I get play counts?

Only for entries of the hot video board (`boardVideo`). Other video modes have likes, comments, shares and saves but no `playCount`.

#### Can I schedule runs and export the data?

Yes. You can schedule runs in Apify, start them through the API, and export every dataset to JSON, CSV, Excel and other formats.

#### What happens with a wrong link or ID?

Invalid IDs or links are skipped. If too many inputs return nothing, the run stops to protect your budget. Missing a field or a mode? Open an issue from the Actor page and it will be looked at.

### More tools from the same developer

- [Douyin Shop 抖音商城 Scraper - Products, Sales, Commission](https://apify.com/clover_folktale/douyin-shop-scraper)
- [Douyin Xingtu 巨量星图 Scraper - KOL Search & Rankings](https://apify.com/clover_folktale/xingtu-scraper)
- [TikTok Scraper - Video Search, Hashtags & Author Profiles](https://apify.com/clover_folktale/tiktok-scraper)
- [Xiaohongshu 小红书 RedNote Scraper - Notes, Comments & User IP](https://apify.com/clover_folktale/xiaohongshu-scraper)
- [Weibo 微博 Scraper - Posts, Comments, User IDs & IP Location](https://apify.com/clover_folktale/weibo-scraper)
- [Bilibili B站 Scraper - Videos, Comments, Subtitles & User IDs](https://apify.com/clover_folktale/bilibili-scraper)

# Actor input Schema

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

What to scrape: the hot search board, videos by keyword, a creator's videos, details of videos, creator profiles, comments of videos, the videos of a hashtag, a creator's followers or following list, creator search, the videos using a sound, or the extended boards (hot videos, topics, rising and city hot spots).

## `keyword` (type: `string`):

Search keyword. Chinese keywords work best, e.g. "美食". In mode board it is an optional filter on the board (leave empty for the full board).

## `creators` (type: `array`):

Douyin profile URLs (https://www.douyin.com/user/MS4w...), v.douyin.com share links or sec_uid values. Many creators hide their followers or following list: those return nothing.

## `videos` (type: `array`):

Douyin video URLs (https://www.douyin.com/video/...), v.douyin.com share links or numeric video IDs.

## `hashtags` (type: `array`):

Hashtag IDs or URLs (https://www.douyin.com/hashtag/1767587367821390). The ID of a hashtag is in its page URL.

## `musics` (type: `array`):

Douyin sound URLs (https://www.douyin.com/music/7482371896877665043) or numeric sound IDs. Every video lists its sound as musicId.

## `board` (type: `string`):

Which board to read: hot videos, hot topics (hashtags), topics rising fastest, rising hot spots, or hot spots of one city.

## `timeWindowHours` (type: `integer`):

How far back the video and topic boards look, in hours. Allowed values: 1, 24, 72 or 168.

## `city` (type: `string`):

Chinese city name (e.g. 杭州) or numeric city code. Empty reads the hot spots of all cities.

## `maxResults` (type: `integer`):

Maximum number of items to return in total for this run. You are charged per item returned. On the free Apify plan a run returns at most 20 results in total; any paid Apify plan removes the limit.

## Actor input object example

```json
{
  "mode": "hot",
  "keyword": "美食",
  "creators": [
    "https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"
  ],
  "videos": [
    "https://www.douyin.com/video/7615131515182385640"
  ],
  "hashtags": [
    "1767587367821390"
  ],
  "musics": [
    "7482371896877665043"
  ],
  "board": "videos",
  "timeWindowHours": 24,
  "maxResults": 20
}
```

# Actor output Schema

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

All scraped items (JSON, CSV, Excel via the dataset API).

# 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 = {
    "keyword": "美食",
    "creators": [
        "https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"
    ],
    "videos": [
        "https://www.douyin.com/video/7615131515182385640"
    ],
    "hashtags": [
        "1767587367821390"
    ],
    "musics": [
        "7482371896877665043"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("clover_folktale/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 = {
    "keyword": "美食",
    "creators": ["https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"],
    "videos": ["https://www.douyin.com/video/7615131515182385640"],
    "hashtags": ["1767587367821390"],
    "musics": ["7482371896877665043"],
}

# Run the Actor and wait for it to finish
run = client.actor("clover_folktale/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 '{
  "keyword": "美食",
  "creators": [
    "https://www.douyin.com/user/MS4wLjABAAAAvcQlQ5vR2pYV04MZ6EzflPQdWTJbVBNnDQTjKiLoH90"
  ],
  "videos": [
    "https://www.douyin.com/video/7615131515182385640"
  ],
  "hashtags": [
    "1767587367821390"
  ],
  "musics": [
    "7482371896877665043"
  ]
}' |
apify call clover_folktale/douyin-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,clover_folktale/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/TeG9vafLjFBRnung5/builds/kXKVJ2uUk9BpYyMFD/openapi.json