# Douyin Trending & Hashtag Scraper: Topics + Videos (`themineworks/douyin-trending-hashtag-scraper`) Actor

Scrape Douyin (Chinese TikTok) trending topics with hotness scores, and every video under any hashtag: description, duration, video and cover URLs. No login, no API key.

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

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Trending & Hashtag Scraper: Topics + Videos

Scrape Douyin, the Chinese TikTok with roughly 750 million users, without a login, a browser, or an API key. Two modes: the live trending board, and every video under any hashtag.

### What it returns

**Trending mode** pulls Douyin's own hot-search board: the topics trending right now, each with a hotness score and a label, plus the timestamp of the board itself. This is the same signal Chinese brands and agencies watch to decide what to publish that day. No input needed at all.

**Hashtag mode** takes one or more Douyin hashtags and returns the videos under each, paginated: description, duration, cover image URL, direct video URL and a canonical share link. It also returns a metadata record per hashtag with its total view count.

### Input

- **mode** (required): `trending` or `hashtag`.
- **hashtags**: hashtag mode only. Douyin hashtag IDs, or full hashtag URLs such as `https://www.douyin.com/hashtag/1575791821492238`, from which the numeric ID is read automatically. Up to 10 hashtags per run.
- **maxItems**: caps records returned **per hashtag**, not per run. With 10 hashtags and the default of 50, a single run can deliver and bill for up to 500 records total, not 50.
- **monitorMode**: returns only records not delivered in an earlier run.

### Example output

```json
{
  "record_type": "video",
  "challenge_id": "1575791821492238",
  "aweme_id": "7657958714196815781",
  "description": "午夜深海巡航 #邮轮 #深海",
  "duration_ms": 18240,
  "cover_url": "https://p3-sign.douyinpic.com/...",
  "play_url": "https://aweme.snssdk.com/aweme/v1/playwm/?video_id=...",
  "share_url": "https://www.douyin.com/video/7657958714196815781",
  "scraped_at": "2026-08-30T00:00:00.000Z"
}
```

**Not available:** author identity (nickname, handle) and engagement counts (likes, comments, shares) are not in this output. Douyin's unsigned video endpoint does not return them at all for this data source, not even as zero, so they are left out entirely rather than shipped as fields that always read null. Same reasoning applies to hashtag-mode "how many creators used this hashtag": Douyin's unsigned hashtag-info endpoint doesn't return that figure, so it isn't in the metadata record either. Total view count per hashtag IS returned.

### What this does not do, and why

Douyin's keyword search, user profile feeds, single video lookup and music feeds all require a signed request (an `a_bogus` signature Douyin computes in browser JavaScript). Those endpoints return an empty stub without it. This actor covers only the endpoints that genuinely work without signing: the trending board, hashtag video feeds, and hashtag metadata. Ten endpoints were tested and exactly three returned real records; the other seven are deliberately not offered rather than shipped as fields that would never populate.

Douyin's ordinary web pages are also protected by a JavaScript challenge that returns an empty page body to any plain HTTP client, which is why this actor reads Douyin's public API rather than its web pages.

### Turning it into a standing watch

Trending topics change hourly and hashtag feeds grow continuously, so this is most useful on a schedule. Set **Monitor mode** to true, save the run as an Apify Task, and add it to a Schedule. Every run after the first returns only what is new, so a daily trend watch bills for new topics rather than re-billing the same board every morning.

### Requirements

This actor needs Apify's **residential proxy**. Douyin does not serve its API to datacenter IP addresses, and a run without residential proxy access will return nothing rather than partial data.

### Who this is for

Brands and agencies tracking what is trending in the Chinese market before planning campaigns. Social listening and competitive research on a platform most Western tools do not cover at all. Anyone building a trend dashboard that needs Chinese social signal alongside Western platforms.

### Pricing

Pay per record delivered, whether a trending topic, a hashtag metadata record or a video. A run that returns no data is never charged for data, though Apify's own small per-run platform start fee still applies regardless of yield.

# Actor input Schema

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

trending = Douyin's live hot-search board (no other input needed). hashtag = every video under the hashtags you supply below.

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

Douyin hashtag IDs, or full hashtag URLs such as https://www.douyin.com/hashtag/1575791821492238. The numeric ID is read out of the URL automatically.

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

Maximum records to return PER HASHTAG (not per run). With multiple hashtags this multiplies: 3 hashtags at the default of 50 can deliver and bill for up to 150 records. Default 50, maximum 500 per hashtag.

## `monitorMode` (type: `boolean`):

Run on a schedule and get ONLY records not delivered in a previous run, so a standing hashtag or trend watch bills for new content instead of the whole feed every time. Keep the input the same across runs.

## Actor input object example

```json
{
  "mode": "trending",
  "hashtags": [
    "1575791821492238"
  ],
  "maxItems": 20,
  "monitorMode": false
}
```

# Actor output Schema

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

No description

# 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": "trending",
    "hashtags": [
        "1575791821492238"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("themineworks/douyin-trending-hashtag-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": "trending",
    "hashtags": ["1575791821492238"],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("themineworks/douyin-trending-hashtag-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": "trending",
  "hashtags": [
    "1575791821492238"
  ],
  "maxItems": 20
}' |
apify call themineworks/douyin-trending-hashtag-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,themineworks/douyin-trending-hashtag-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/DUUS9JX7doct4lx0O/builds/2zSr630U8goiDKwq5/openapi.json