# Douyin Scraper — Hot List, Video Detail, No Watermark 抖音 (`technicaldost/douyin-hot-video-scraper`) Actor

Scrape Douyin (抖音) hot-search/trending list, video details (stats, author, music, hashtags) and watermark-free play URLs. Hot list works with no account or cookies. Ideal for CN e-commerce operators and SEA cross-border sellers tracking Douyin trends.

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

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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 — Hot List, Video Detail, No Watermark 抖音

Scrape **Douyin (抖音)** — China's largest short-video platform — through a simple API:

- 🔥 **Hot-search / trending list** — the real-time Douyin hot board (热搜榜), with rank and heat value. **Works with no login, no cookies, no account.**
- 🎬 **Video detail** — full stats for any video URL: likes, comments, shares, plays, author, music, hashtags, cover and play URLs.
- 💧 **Watermark-free play URL** — best-effort direct no-watermark CDN link per video.
- 🔎 **Keyword search** — search videos by keyword (requires login cookies).

Built for **CN e-commerce operators** and **SEA cross-border sellers** tracking Douyin trends, competitor creatives and viral products.

### What works without login (verified)

| Capability | Keyless? | Notes |
|---|---|---|
| Hot list (`HOT_LIST`) | ✅ Yes | Verified live: ~50 trending entries per run. |
| Short-link / ID resolution | ✅ Yes | `v.douyin.com` short links and share URLs resolve without login. |
| Video detail (`VIDEO_URLS`) | ❌ No | Douyin rejects anonymous detail requests (signed params required). Provide `cookies` from a logged-in session. |
| Search (`SEARCH`) | ❌ No | Douyin answers anonymous search with "请先登录" (please log in). `cookies` required. |
| No-watermark URL | ⚠️ Best-effort | Derived from the video's `play_addr` via the legacy play endpoint; `null` when unavailable. |

**How to get cookies:** log in at [douyin.com](https://www.douyin.com/) in your browser, open DevTools → Network → any request to `www.douyin.com` → copy the full `cookie:` request header value into the `cookies` input field. The field is stored encrypted.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `HOT_LIST` | One of `HOT_LIST`, `VIDEO_URLS`, `SEARCH`. |
| `keywords` | array | `[]` | Keywords for `SEARCH` mode. |
| `videoUrls` | array | `[]` | Video URLs for `VIDEO_URLS` mode — full `https://www.douyin.com/video/<id>` URLs or `v.douyin.com` short links. |
| `maxVideosPerKeyword` | integer | `10` | Max videos per keyword in `SEARCH` mode (1–50). |
| `cookies` | string | — | Cookie header from a logged-in douyin.com session. Required for `SEARCH`, strongly recommended for `VIDEO_URLS`. Stored encrypted. |
| `proxyConfiguration` | object | — | Optional Apify proxy. Recommended for large runs. |

### Output

One dataset item per hot-list entry or video. Hot-list entries have `type: "hot_item"`; videos have `type: "video"`. Fields that don't apply are `null`.

| Field | Description |
|---|---|
| `type` | `hot_item` or `video` |
| `keyword` | Search keyword (videos from search only) |
| `rank` | Position on the hot board (hot items only) |
| `hotValue` | Douyin heat value 热度 (hot items only) |
| `awemeId` | Douyin video ID |
| `url` | Canonical `https://www.douyin.com/video/<id>` URL |
| `desc` | Hot-search phrase or video description |
| `authorName` / `authorId` | Video author nickname / unique ID |
| `diggCount` / `commentCount` / `shareCount` / `playCount` | Engagement stats |
| `publishTime` | ISO 8601 publish time |
| `duration` | Video duration (ms) |
| `music` | Soundtrack title |
| `hashtags` | Array of hashtag names |
| `coverUrl` | Cover image URL |
| `playUrl` | Standard play CDN URL |
| `noWatermarkUrl` | Watermark-free play URL (best-effort, may be `null`) |
| `scrapedAt` | ISO 8601 scrape timestamp |

#### Example output (hot list)

```json
{
  "type": "hot_item",
  "keyword": null,
  "rank": 1,
  "hotValue": 11456032,
  "awemeId": "7290735283778622779",
  "url": "https://www.douyin.com/video/7290735283778622779",
  "desc": "今年第18号台风沙德尔生成",
  "authorName": null,
  "authorId": null,
  "diggCount": null,
  "commentCount": null,
  "shareCount": null,
  "playCount": null,
  "publishTime": "2026-08-19T06:43:36.000Z",
  "duration": null,
  "music": null,
  "hashtags": [],
  "coverUrl": "https://p3-sign.douyinpic.com/...",
  "playUrl": null,
  "noWatermarkUrl": null,
  "scrapedAt": "2026-08-20T02:52:00.000Z"
}
```

### Example inputs

**Trending hot list (no login needed):**

```json
{ "mode": "HOT_LIST" }
```

**Details for specific videos:**

```json
{
  "mode": "VIDEO_URLS",
  "videoUrls": ["https://v.douyin.com/abc123/", "https://www.douyin.com/video/7290735283778622779"],
  "cookies": "sessionid=...; ttwid=...; ..."
}
```

**Search (login required):**

```json
{
  "mode": "SEARCH",
  "keywords": ["连衣裙", "手机壳"],
  "maxVideosPerKeyword": 10,
  "cookies": "sessionid=...; ttwid=...; ..."
}
```

### Pricing (pay-per-event)

- **$0.50 per 1,000 hot-list items** (`hot-list-item` event)
- **$2.00 per 1,000 videos** (`video` event)
- **No start fee.** You only pay for items actually delivered to the dataset.

### Notes & limitations

- Douyin's anti-bot rules change frequently. The hot list currently works from datacenter IPs with anonymous cookies; if Douyin tightens this, attach a residential proxy via `proxyConfiguration`.
- `VIDEO_URLS` without cookies: the actor still resolves short links to canonical IDs, but detail fetches will fail with a clear error — supply `cookies`.
- All timestamps are UTC ISO strings. Counts are integers as reported by Douyin at scrape time.

# Actor input Schema

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

HOT\_LIST: scrape the Douyin hot-search/trending list (works without cookies). VIDEO\_URLS: fetch full details for specific video URLs. SEARCH: search videos by keyword (requires cookies).

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

Keywords to search for (SEARCH mode only). Douyin search requires login - provide logged-in cookies below.

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

Douyin video URLs (VIDEO\_URLS mode). Accepts full URLs like https://www.douyin.com/video/1234567890 and v.douyin.com short links.

## `maxVideosPerKeyword` (type: `integer`):

Maximum number of videos to scrape per keyword in SEARCH mode.

## `cookies` (type: `string`):

Cookie header string from a logged-in douyin.com session (copy the whole `cookie:` request header from your browser devtools). Required for SEARCH mode and strongly recommended for VIDEO\_URLS mode - without it, video detail requests are usually rejected by Douyin.

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

Optional Apify proxy settings. Recommended for large runs to avoid rate limits.

## Actor input object example

```json
{
  "mode": "HOT_LIST",
  "keywords": [],
  "videoUrls": [],
  "maxVideosPerKeyword": 10
}
```

# Actor output Schema

## `resultsDatasetUrl` (type: `string`):

Dataset containing hot-list items and/or video details.

# 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": "HOT_LIST",
    "keywords": [],
    "videoUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("technicaldost/douyin-hot-video-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": "HOT_LIST",
    "keywords": [],
    "videoUrls": [],
}

# Run the Actor and wait for it to finish
run = client.actor("technicaldost/douyin-hot-video-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": "HOT_LIST",
  "keywords": [],
  "videoUrls": []
}' |
apify call technicaldost/douyin-hot-video-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,technicaldost/douyin-hot-video-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/NvtI4UKMo2LqxJe2G/builds/GY32F8yHAzr31fez5/openapi.json