# Douyin Scraper (`ecommerce_leads/douyin-scraper`) Actor

Download Douyin videos without watermark, get any comments, profiles, trending, series and keywords. No login or cookies needed.

- **URL**: https://apify.com/ecommerce\_leads/douyin-scraper.md
- **Developed by:** [Monster Leads](https://apify.com/ecommerce_leads) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 50.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.92 / 1,000 douyin video listeds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Douyin Scraper — Download Douyin Videos Without Watermark

**Download Douyin videos**, scrape Douyin comments, Douyin profiles, Douyin trending hot-search boards, Douyin category feeds, Douyin keyword suggestions and Douyin mini-dramas — all from one Douyin scraper. No Douyin login, no Douyin cookies, no browser.

Paste any Douyin link and get back a **watermark-free MP4 URL** in about a second, plus the full Douyin metadata around it: creator, follower count, likes, comments, shares, saves, the Douyin sound, the hashtags and the cover image.

> **Douyin (抖音) is the Chinese version of TikTok**, run by ByteDance for mainland China. Douyin has its own catalogue, its own creators and its own trending boards — Douyin content does **not** appear on TikTok. This Douyin scraper talks to Douyin directly.

***

### ⬇️ Download Douyin videos (the main feature)

This is what most people come here for, so it is the default mode. Give the Douyin Scraper a list of Douyin links and it returns a direct MP4 URL for each Douyin video.

#### Input

```json
{
  "mode": "download",
  "videoUrls": [
    "https://www.douyin.com/video/7681251317267942708",
    "https://v.douyin.com/iAbCdEf/",
    "7673317030539414811"
  ]
}
```

**Every Douyin link format works.** You do not have to clean anything up first:

| What you paste | Works? |
| --- | --- |
| `https://www.douyin.com/video/7681251317267942708` | ✅ Full Douyin link |
| `https://v.douyin.com/iAbCdEf/` | ✅ Douyin short link (redirect followed for you) |
| `7.65 复制打开抖音，看看【…】https://v.douyin.com/iAbCdEf/ 很有意思` | ✅ The whole Douyin share caption, emojis and all |
| `7681251317267942708` | ✅ Bare Douyin video ID |
| `https://www.iesdouyin.com/share/video/7681251317267942708/` | ✅ Douyin share-domain link |

#### Output — one row per Douyin video

Real output from this Douyin scraper, trimmed for width:

```json
{
  "type": "video",
  "aweme_id": "7681251317267942708",
  "kind": "video",
  "desc": "别让《爱情公寓》只活在回忆里！…#爱情公寓 #我的青春还有售后",
  "hashtags": ["爱情公寓", "我的青春还有售后", "发癫吧后浪"],
  "create_time": 1788430695,
  "create_time_iso": "2026-09-03T10:18:15+00:00",

  "download_url": "https://v5-dy-ov-experiment.zjcdn.com/2732ddeb…/video/tos/cn/…",
  "download_url_watermarked": "https://v5-dy-ov-experiment.zjcdn.com/fcfe0721…",
  "download_is_watermark_free": true,
  "image_urls": [],

  "cover": "https://p3-pc-sign.douyinpic.com/image-cut-tos/…",
  "origin_cover": "https://p3-pc-sign.douyinpic.com/tos-cn-p-0015/…",
  "duration_seconds": 62.72,
  "width": 1920,
  "height": 1080,
  "file_size_bytes": 24467850,

  "author_nickname": "发癫吧，后浪！",
  "author_unique_id": "shimaobianjibu",
  "author_sec_uid": "MS4wLjABAAAAO8o8Scrw0S3LwRZl8Ud7hSU032OYbSVBKjlDpqjEOYr1qNTvyOd2b-zZPskHQ4kd",
  "author_follower_count": 4273648,
  "author_url": "https://www.douyin.com/user/MS4wLjABAAAAO8o8…",

  "digg_count": 743135,
  "comment_count": 9821,
  "share_count": 79690,
  "collect_count": 17896,

  "music_title": "@发癫吧，后浪！创作的原声",
  "music_url": "https://sf5-hl-cdn-tos.douyinstatic.com/obj/…",

  "share_url": "https://www.iesdouyin.com/share/video/7681251317267942708/…",
  "douyin_url": "https://www.douyin.com/video/7681251317267942708"
}
```

#### 🚫 Watermark: read this before you use the URL

The Douyin Scraper returns **two** Douyin video URLs, and they are not the same file:

| Field | Watermark | Resolution (this example) | Use it for |
| --- | --- | --- | --- |
| `download_url` | **None** — clean | 1920×1080, 24.5 MB | Almost always this one |
| `download_url_watermarked` | Douyin logo + creator ID burned in | 720×720, 28.3 MB | Only if you specifically want the Douyin-branded file |

`download_is_watermark_free` tells you which file `download_url` actually points at. It is `true` when Douyin served the clean stream. On rare Douyin videos the clean stream is withheld, the actor falls back to the watermarked file, and this flag goes `false` — so you always know what you got instead of finding a watermark later.

**The Douyin CDN URLs expire in a few hours.** Download the file during or shortly after the run; do not store the URL and fetch it next week.

#### 📸 Douyin photo posts

Not every Douyin post is a video. Douyin photo slideshows (图文) come back with `kind: "image_post"`, an empty `download_url`, and every picture in `image_urls`. That is a normal result, not a Douyin scraping failure.

***

### Reading your Douyin results

Every Douyin row lands in the same dataset, and the tabs above the results table switch between views of it.

**Overview** is the default and works for every Douyin mode. Because a Douyin video, a Douyin profile and a Douyin trend have completely different fields, this view maps each one onto five shared columns:

| Column | Douyin video | Douyin profile | Douyin comment | Douyin trend | Douyin mini-drama |
| --- | --- | --- | --- | --- | --- |
| **Douyin result** | caption | creator nickname | comment text | trend word | drama title |
| **Creator** | video author | the creator | comment author | — | — |
| **Likes / followers / hot value** | likes | followers | comment likes | hot value | plays |
| **Douyin ID** | `aweme_id` | `sec_uid` | `comment_id` | — | `series_id` |
| **Open on Douyin** | video link | profile link | — | search link | video link |

**The per-type views** — Douyin videos, Douyin comments, Douyin profiles, Douyin trends, Douyin keywords, Douyin mini-dramas — show the complete field set for one Douyin record type, with proper labels, clickable Douyin links and image previews. Switch to these when you want everything.

**Every field is always kept in the dataset**, whichever view you are looking at. A view narrows the columns you get back, so ask for the one you want:

```
https://api.apify.com/v2/datasets/<datasetId>/items                  ← all fields
https://api.apify.com/v2/datasets/<datasetId>/items?view=videos      ← Douyin video columns
https://api.apify.com/v2/datasets/<datasetId>/items?view=profiles    ← Douyin profile columns
```

Leave `?view=` off — in the API, in the Apify Python/JS clients, and in JSON/CSV/Excel exports — to get every field of every Douyin row.

***

### All Douyin Scraper modes

Pick one in the **What do you want to do?** dropdown. **The mode decides everything** — each Douyin mode reads only its own section of the form and ignores the rest.

> ⚠️ **The most common mistake:** pasting Douyin video links but leaving the mode on something else. The input form shows every mode's fields at once (Apify input forms cannot hide fields based on another field's value), so Douyin video links sit in plain view even during a Douyin profile run — where nothing reads them. Each section is captioned with the mode that owns it, and if you fill in a field the selected mode ignores, the Douyin Scraper says so in the run log before it scrapes anything:
>
> ```
> Mode is 'profile', so these inputs are IGNORED by this run: videoUrls
>   • "videoUrls" is used by the ⬇️  Download Douyin videos mode.
>   If that is not what you wanted, change "What do you want to do?" at the top
>   of the input form and run again.
> ```
>
> If a Douyin run returns the wrong kind of row, check that warning first — it names the field and the mode that would have used it.

| Mode | What this Douyin scraper returns | Price per result |
| --- | --- | --- |
| ⬇️ **Download Douyin videos** | Watermark-free MP4 URL + full Douyin metadata | $0.01 |
| 💬 **Douyin comments** | Douyin comments and replies with likes and IP region | $0.001 |
| 👤 **Douyin profile** | Douyin creator stats — followers, total likes, bio | $0.01 profile, $0.001 per video |
| 🔥 **Douyin trending** | Douyin hot-search board entries with rank | $0.001 |
| 🧭 **Douyin feed** | Douyin videos from a category feed | $0.001 |
| 🔗 **Related Douyin videos** | Douyin videos related to one Douyin video | $0.001 |
| 🔎 **Douyin keywords** | Douyin search-box suggestions for SEO research | $0.001 |
| 🎬 **Douyin mini-dramas** | Douyin 短剧 catalogue with synopsis | $0.001 |
| 🌐 **Translate Douyin text** | Douyin captions/comments translated | $0.01 |

***

### 💬 Scrape Douyin comments

Pulls Douyin comments on any Douyin video, newest page after page, and optionally the reply thread under each Douyin comment.

#### Input

```json
{
  "mode": "comments",
  "videoUrl": "https://www.douyin.com/video/7681251317267942708",
  "maxComments": 100,
  "includeReplies": true,
  "maxRepliesPerComment": 10
}
```

| Property | What it does |
| --- | --- |
| `videoUrl` | The Douyin video to read comments from. Any Douyin link format from the table above. |
| `maxComments` | How many top-level Douyin comments to collect. Douyin pages these 20 at a time and the Douyin Scraper keeps going until it hits your number or Douyin runs out. Default `50`. |
| `includeReplies` | Also fetch the reply thread under every Douyin comment that has replies. Each reply is its own billable Douyin result. **See the note below** — Douyin is currently blocking this. Default `false`. |
| `maxRepliesPerComment` | Cap on replies fetched per Douyin comment. Default `10`. |

> ⚠️ **Douyin is currently blocking comment replies for anonymous sessions.** Douyin's reply endpoint answers with an empty response no matter which IP asks. When the Douyin Scraper detects this it says so in the log, stops asking, and finishes the run with top-level Douyin comments only — **you are never charged for replies that could not be fetched.** Top-level Douyin comments are unaffected and come back in full.

#### Output

```json
{
  "type": "comment",
  "comment_id": "7681994953413247759",
  "video_id": "7681251317267942708",
  "is_reply": false,
  "parent_comment_id": "",
  "message": "答应我，不论你什么时候看到这条评论，你都叫我去喝水，谢谢",
  "author_nickname": "青梅爆爆",
  "author_uid": "1901496367066764",
  "like_count": 2517,
  "reply_count": 509,
  "location": "广西",
  "is_hot": true,
  "create_time_iso": "2026-09-04T20:23:50+00:00"
}
```

`location` is the coarse IP region Douyin shows publicly next to each Douyin comment (a Chinese province, or a country for overseas users). Replies carry `is_reply: true` and point at their parent through `parent_comment_id`.

***

### 👤 Scrape Douyin profiles

Douyin creator stats, plus their recent Douyin videos if you want them.

#### Input

```json
{
  "mode": "profile",
  "profileUrls": [
    "https://www.douyin.com/user/MS4wLjABAAAAO8o8Scrw0S3LwRZl8Ud7hSU032OYbSVBKjlDpqjEOYr1qNTvyOd2b-zZPskHQ4kd"
  ],
  "maxProfileVideos": 0
}
```

> ⚠️ **Douyin profiles need a `sec_uid`**, the long `MS4wLjAB…` string in the Douyin profile URL. Douyin's own profile API rejects short numeric UIDs, so this Douyin scraper cannot accept them either. Copy the Douyin profile link straight from the browser and it will be right.

| Property | What it does |
| --- | --- |
| `profileUrls` | One or more Douyin profile links, or bare `sec_uid` values. |
| `maxProfileVideos` | How many of the creator's recent Douyin videos to include. **See the note below** — Douyin is currently restricting this. Default `0` (profile stats only). |

> ⚠️ **Douyin currently restricts creator video lists for anonymous sessions.** Douyin's profile-video endpoint returns an empty response regardless of IP, so `maxProfileVideos` usually yields nothing — while the **Douyin profile stats themselves come back in full and are unaffected**. The run logs a warning and you are not charged for videos that were not returned. To collect a specific creator's Douyin videos, paste their Douyin video links into the ⬇️ Download mode, or use the 🧭 Feed and 🔗 Related modes.

#### Output

```json
{
  "type": "profile",
  "sec_uid": "MS4wLjABAAAAO8o8Scrw0S3LwRZl8Ud7hSU032OYbSVBKjlDpqjEOYr1qNTvyOd2b-zZPskHQ4kd",
  "uid": "3380350436780335",
  "nickname": "发癫吧，后浪！",
  "unique_id": "shimaobianjibu",
  "signature": "后浪是一种精神，大家都可以是后浪！…",
  "avatar": "https://p3-pc.douyinpic.com/aweme/1080x1080/…",
  "follower_count": 4273648,
  "following_count": 12,
  "total_favorited": 89234567,
  "aweme_count": 342,
  "profile_url": "https://www.douyin.com/user/MS4wLjABAAAAO8o8…"
}
```

The creator's Douyin videos follow as separate rows in the same video shape as the download mode, tagged `"source": "profile"`.

***

### 🔥 Scrape Douyin trending (hot search)

Douyin's real-time hot-search board — what all of Douyin is watching right now.

#### Input

```json
{ "mode": "trending", "board": "hot", "maxTrending": 50 }
```

`board` picks which Douyin board to read: `hot` (Douyin's main real-time board), `total`, `shopping`, `music`, `sport`, `car`, `travel`.

#### Output

```json
{
  "type": "trend",
  "rank": 1,
  "word": "总书记心系人民教师",
  "hot_value": 0,
  "view_count": 0,
  "video_count": 0,
  "board": "hot",
  "active_time": "2026-09-09 23:57:12",
  "search_url": "https://www.douyin.com/search/总书记心系人民教师"
}
```

> **Note on zeros:** Douyin's public hot-search endpoint returns the ranking and the terms, but leaves `hot_value`, `view_count` and `video_count` at `0` for most entries — Douyin only fills those in for some boards. The rank order is the reliable signal, and it is exact.

***

### 🧭 Scrape the Douyin feed by category

Pull fresh Douyin videos from Douyin's curated feed or any of its 15 category channels.

#### Input

```json
{ "mode": "feed", "category": "food", "maxFeedVideos": 50 }
```

`category` accepts: `all` (Douyin's curated 精选 feed), `game`, `anime`, `music`, `food`, `knowledge`, `sports`, `drama`, `movie`, `vlog`, `kids`, `car`, `rural`, `animal`, `travel`, `beauty`.

Output rows are Douyin videos in the same shape as the download mode, tagged `"source": "feed"` with the `feed_category` you asked for.

> Douyin recommends a **different set of videos on every run**, which is what makes this mode useful for sampling Douyin trends over time. It also means two runs with identical input return different Douyin videos.

***

### 🔗 Related Douyin videos

Given one Douyin video, get the Douyin videos Douyin itself recommends next to it — a fast way to expand a Douyin seed into a topic cluster.

```json
{ "mode": "related", "videoUrl": "https://www.douyin.com/video/7681251317267942708", "maxRelated": 20 }
```

Rows come back in the video shape, tagged `"source": "related"` and `related_to` with your seed Douyin video ID.

***

### 🔎 Douyin keyword suggestions (Douyin SEO)

Read the suggestions out of Douyin's own search box. This is the cheapest Douyin keyword research there is — it is what Douyin users actually type.

#### Input

```json
{ "mode": "keywords", "keyword": "美食", "suggestionType": "autocomplete" }
```

| `suggestionType` | What Douyin returns |
| --- | --- |
| `autocomplete` | Douyin's type-ahead completions — prefix matches, e.g. `美食` → `美食测评`, `美食盘点`, `美食p图` |
| `related` | Broader Douyin topic suggestions — e.g. `美食` → `酸菜鱼`, `牛肉`, `附近美食`, `出餐快又暴利的小吃` |

#### Output

```json
{
  "type": "keyword",
  "word": "美食测评",
  "seed_keyword": "美食",
  "suggestion_type": "autocomplete",
  "group_id": "6595533951412999437",
  "search_url": "https://www.douyin.com/search/美食测评"
}
```

***

### 🎬 Douyin mini-dramas (短剧)

Douyin's mini-drama catalogue — the short vertical serials that dominate Douyin.

```json
{ "mode": "series", "maxSeries": 24 }
```

```json
{
  "type": "series",
  "series_id": "7676329928593246262",
  "name": "嫌疑人的秘密",
  "desc": "男主陈锋就职于大型军工通讯设备研发公司，因核心机密…",
  "cover": "https://p3-sign.douyinpic.com/…",
  "aweme_id": "7676329918745054500",
  "douyin_url": "https://www.douyin.com/video/7676329918745054500"
}
```

***

### 🌐 Translate Douyin text

Translate Douyin captions, Douyin comments or Douyin hashtags using Douyin's own translation engine — the same one the Douyin app uses, so Douyin slang and internet shorthand come out better than with a generic translator.

```json
{ "mode": "translate", "text": "今天天气很好", "targetLanguage": "en" }
```

```json
{
  "type": "translation",
  "source_text": "今天天气很好",
  "translation": "The weather is great today",
  "target_language": "en",
  "model": "CLA-X32"
}
```

***

### 💰 Pricing — $1 per 1,000 Douyin results

This Douyin Scraper is **pay per result**. You are charged for Douyin data you actually receive, and nothing else.

| Douyin result | Price | Why |
| --- | --- | --- |
| Douyin video downloaded | **$0.01** | One dedicated Douyin request, its own proxy and visitor session, to produce one complete Douyin video |
| Douyin profile scraped | **$0.01** | Same — one Douyin profile lookup per result |
| Douyin text translated | **$0.01** | Same — one Douyin translation call per result |
| Douyin comment | **$0.001** | Arrives 20 per Douyin request |
| Douyin video in a feed / related / profile list | **$0.001** | Arrives in a batch from one Douyin request |
| Douyin trend | **$0.001** | Up to 50 per Douyin request |
| Douyin keyword suggestion | **$0.001** | 10–15 per Douyin request |
| Douyin mini-drama | **$0.001** | Batched per Douyin request |

**List results are $1 per 1,000.** Single results cost 10× because one of them *is* a whole Douyin request — the same work that produces ten list rows.

#### You are never charged for a Douyin video you did not get

Douyin videos get deleted, made private, age-gated and region-locked all the time. When Douyin refuses one, the Douyin Scraper still writes a row so you can see which input failed:

```json
{ "type": "video", "input": "https://www.douyin.com/video/1111111111111111111",
  "error": "douyin 限制了这条视频 (filter_detail): 1111111111111111111" }
```

**That row is free.** Charging happens only after a row carrying real Douyin data is stored. Rows with an `error` field are never billed, so a run against a list of dead Douyin links costs you nothing.

***

### Example: download Douyin videos from the API

```python
from apify_client import ApifyClient

client = ApifyClient('<YOUR_APIFY_TOKEN>')

run = client.actor('douyin-scraper').call(run_input={
    'mode': 'download',
    'videoUrls': [
        'https://www.douyin.com/video/7681251317267942708',
        'https://v.douyin.com/iAbCdEf/',
    ],
})

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    if item.get('error'):
        print('Douyin refused:', item['input'], '-', item['error'])
        continue
    print(item['author_nickname'], '|', item['digg_count'], 'likes')
    print('  MP4:', item['download_url'])
```

Saving the Douyin videos to disk:

```python
import httpx

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    url = item.get('download_url')
    if not url:
        continue
    r = httpx.get(url, follow_redirects=True, timeout=120)
    with open(f"douyin_{item['aweme_id']}.mp4", 'wb') as f:
        f.write(r.content)
```

***

### Frequently asked questions

**Do I need a Douyin account or Douyin cookies?**
No. This Douyin Scraper maintains its own pool of anonymous Douyin visitor sessions and rotates residential proxies automatically. You never log into Douyin.

**Are the Douyin videos really watermark-free?**
Yes — `download_url` is Douyin's own clean player stream, and it is also the higher-resolution file (1080p versus the 720p watermarked one in the example above). Check `download_is_watermark_free` on any row to be certain.

**How long do the Douyin download URLs stay valid?**
A few hours. Douyin signs its CDN URLs with an expiry. Fetch the file during or right after the run.

**Can I download private or paid Douyin videos?**
No. This Douyin Scraper only reads Douyin content that is publicly visible to any Douyin visitor. Private, deleted, paid and region-locked Douyin videos come back as free error rows.

**Why did I get no Douyin comment replies / no videos from a Douyin profile?**
Douyin has restricted both of those endpoints for anonymous sessions — they return an empty response no matter which IP asks, so no Douyin scraper without logged-in Douyin accounts can read them right now. The Douyin Scraper detects this, logs it plainly, and **does not charge you** for what it could not fetch. Top-level Douyin comments and Douyin profile stats are unaffected and come back in full. These are Douyin-side restrictions that Douyin changes from time to time.

**Why is `play_count` always 0?**
Douyin does not expose play counts on its web API at all — for any Douyin video, to anyone. Likes, comments, shares and saves are all real. The field is kept so the row shape stays stable.

**Why did Douyin trending return `hot_value: 0`?**
Douyin only populates hot values on some of its boards. The `rank` ordering is always correct.

**How many Douyin videos can I scrape in one run?**
There is no hard cap. Douyin comments page in 20s, Douyin feeds in ~20s, and the Douyin Scraper keeps requesting until it reaches your limit.

**Is scraping Douyin legal?**
This Douyin Scraper collects only public Douyin data — no login, no private Douyin content, no personal data behind a Douyin privacy setting. You are responsible for how you use Douyin data, including copyright in the Douyin videos themselves. Douyin videos belong to their creators; downloading a Douyin video does not grant you a licence to republish it.

***

### Setup for self-hosted use

This Douyin Scraper talks to a crawler backend that handles Douyin proxy rotation and Douyin visitor cookies. Point the actor at yours with two environment variables:

| Variable | Value |
| --- | --- |
| `CRAWLER_URL` | `https://your-crawler-domain` |
| `CRAWLER_API_KEY` | Your API key — **store it as a secret** |

Both can also be passed as input (`crawlerUrl`, `crawlerApiKey`) for local testing. Give each actor its own API key so one leak does not force you to rotate every actor at once.

# Actor input Schema

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

Pick the Douyin task to run. **Download videos** is the default and the most used: paste Douyin links and get watermark-free MP4 URLs back. Every other mode reveals its own fields below.

## `videoUrls` (type: `array`):

Douyin links to download. Paste anything Douyin gives you — full links (`https://www.douyin.com/video/7681251317267942708`), short links (`https://v.douyin.com/iAbCdEf/`), the whole share caption with emojis, or a bare video ID. Each Douyin link becomes one row in the output.

## `includeRawData` (type: `boolean`):

Adds a `raw` field with the full untouched Douyin payload (150+ fields per video). Leave off unless you need a Douyin field this actor does not already map — it makes each row roughly 20× larger.

## `videoUrl` (type: `string`):

The Douyin video whose comments (or related videos) you want. Accepts a full Douyin link, a `v.douyin.com` short link, a share caption or a bare ID. Example: `https://www.douyin.com/video/7681251317267942708`

## `maxComments` (type: `integer`):

How many top-level Douyin comments to fetch. Douyin serves these in pages of 20 and the actor keeps paging until it reaches this number or Douyin runs out.

## `includeReplies` (type: `boolean`):

Fetches the reply thread under every Douyin comment that has one. ⚠️ Douyin is currently blocking its reply endpoint for anonymous sessions, so this often returns nothing — the run then continues with top-level Douyin comments only and you are not charged for the replies. Each reply that does come back is billed as one Douyin comment.

## `maxRepliesPerComment` (type: `integer`):

Cap on replies fetched per Douyin comment. Only applies when replies are enabled.

## `profileUrls` (type: `array`):

Douyin creator profiles to scrape. Paste the profile link (`https://www.douyin.com/user/MS4wLjABAAAA...`) or the bare `sec_uid`. Douyin numeric UIDs do **not** work here — Douyin's profile API only accepts `sec_uid`.

## `maxProfileVideos` (type: `integer`):

How many of the creator's recent Douyin videos to include. ⚠️ Douyin currently restricts creator video lists for anonymous sessions, so this usually returns nothing while the Douyin profile stats still come back in full. Leave at 0 for profile stats only. To collect a creator's Douyin videos reliably, use the Download mode with their Douyin video links.

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

Which Douyin trending board to read.

## `maxTrending` (type: `integer`):

How many Douyin hot-search entries to return.

## `category` (type: `string`):

Which Douyin category feed to pull from. `all` is Douyin's main curated feed (精选).

## `maxFeedVideos` (type: `integer`):

How many Douyin videos to pull from the category feed. Douyin returns a fresh recommendation set on every run, so repeated runs give different videos.

## `maxRelated` (type: `integer`):

How many Douyin videos related to the target video to return.

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

Seed keyword for Douyin search suggestions. Returns the terms Douyin's own search box suggests — useful for Douyin SEO and hashtag research. Example: `美食` (food).

## `suggestionType` (type: `string`):

`autocomplete` mirrors Douyin's type-ahead dropdown (prefix matches). `related` returns broader Douyin topic suggestions around the keyword.

## `maxSeries` (type: `integer`):

How many Douyin mini-dramas (短剧) to list from Douyin's series catalogue.

## `text` (type: `string`):

Douyin caption, comment or hashtag text to translate using Douyin's own translation engine. Example: `今天天气很好`

## `targetLanguage` (type: `string`):

Target language code for the Douyin translation.

## `crawlerUrl` (type: `string`):

Base URL of the Douyin crawler backend, e.g. `https://ping.example.com`. Falls back to the `CRAWLER_URL` environment variable.

## `crawlerApiKey` (type: `string`):

API key for the Douyin crawler backend. Falls back to the `CRAWLER_API_KEY` environment variable.

## Actor input object example

```json
{
  "mode": "download",
  "videoUrls": [
    "https://www.douyin.com/video/7681251317267942708"
  ],
  "includeRawData": false,
  "maxComments": 50,
  "includeReplies": false,
  "maxRepliesPerComment": 10,
  "maxProfileVideos": 0,
  "board": "hot",
  "maxTrending": 50,
  "category": "all",
  "maxFeedVideos": 20,
  "maxRelated": 20,
  "suggestionType": "autocomplete",
  "maxSeries": 24,
  "targetLanguage": "en"
}
```

# Actor output Schema

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

Every row from this run, whatever mode produced it: Douyin videos, comments, profiles, trends, keywords, mini-dramas or translations. Rows carrying an `error` field are Douyin items that could not be fetched — they are recorded so you can see which input failed, and they are never charged. Start here if you are not sure which mode the run used.

## `videos` (type: `string`):

Downloadable Douyin videos with watermark-free MP4 URLs, cover images, duration, resolution, creator and engagement stats. Produced by the Download, Feed, Related and Profile modes. Use `download_url` for the file and check `download_is_watermark_free` to confirm the clean stream was served. Douyin CDN URLs expire within hours, so fetch the file promptly.

## `comments` (type: `string`):

Douyin comments and replies with likes, reply counts, author and the coarse IP region Douyin shows publicly. Produced by the Comments mode.

## `profiles` (type: `string`):

Douyin creator profiles with follower counts, total likes, video counts, bio and verification status. Produced by the Profile mode.

## `trends` (type: `string`):

Douyin hot-search board entries with rank, hot value and view counts, plus a ready-made Douyin search URL per trend. Produced by the Trending mode.

## `keywords` (type: `string`):

Keyword suggestions taken from Douyin's own search box — what Douyin users actually type. Produced by the Keywords mode and used for Douyin SEO and hashtag research.

## `series` (type: `string`):

Douyin mini-drama (短剧) catalogue entries with synopsis, cover and the first Douyin video of each series. Produced by the Series mode.

# 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": "download",
    "videoUrls": [
        "https://www.douyin.com/video/7681251317267942708"
    ],
    "maxComments": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("ecommerce_leads/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": "download",
    "videoUrls": ["https://www.douyin.com/video/7681251317267942708"],
    "maxComments": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("ecommerce_leads/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": "download",
  "videoUrls": [
    "https://www.douyin.com/video/7681251317267942708"
  ],
  "maxComments": 50
}' |
apify call ecommerce_leads/douyin-scraper --silent --output-dataset

```

## MCP server setup

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