# Douyin Hashtag Detail Scraper (`opspilot.cc/douyin-hashtag-detail`) Actor

- **URL**: https://apify.com/opspilot.cc/douyin-hashtag-detail.md
- **Developed by:** [wang wei](https://apify.com/opspilot.cc) (community)
- **Categories:**
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.10 / actor start

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 Hashtag Detail Scraper

**EN — Get details of a Douyin hashtag (challenge) by its numeric `ch_id`.** Returns the rich `ch_info` object: name, description, total view count, total user count, share metadata, author info, and challenge flags. One run = one upstream call.

**ZH — 抖音话题详情 — 通过 `ch_id`(话题 ID)抓取话题元数据。** 返回完整的 `ch_info`:名称、描述、总播放量、总参与用户数、分享链接、作者信息、是否官方话题等。一次运行 = 一次上游请求。

Built for **influencer research**, **trend analysis**, **brand monitoring**, **competitor benchmarking**, and **content ops workflows** on Douyin (TikTok China) — China's #1 short-video platform with 750M+ daily active users.

**5 free runs / day.** No API key required — the Actor's built-in upstream key is already configured.

### Input

| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
| `chId` | integer | yes | — | Douyin challenge id (numeric). Example: `1575791821492238`. |

> A real-world example: ch\_id `1575791821492238` = 深海 (Deep Sea) — 5.28 billion cumulative views.

```json
{
  "chId": 1575791821492238
}
```

### Output

The Actor pushes one item (the normalized `ch_info`) to the default dataset and writes a `SUMMARY` record to the default key-value store.

```json
{
  "ch_id": 1575791821492238,
  "cha_name": "深海",
  "desc": "深海是一个挑战话题",
  "view_count": 5283529674,
  "user_count": 52345678,
  "is_challenge": true,
  "is_pgcshow": false,
  "share_info": {
    "share_title": "深海",
    "share_desc": "深海挑战话题",
    "share_url": "https://www.iesdouyin.com/share/challenge/1575791821492238"
  },
  "author": { /* creator profile when available */ },
  "rawData": { /* full upstream ch_info object */ }
}
```

### How to find a `chId`

The `chId` is the numeric challenge id Douyin assigns to every hashtag. You can grab it from any public hashtag URL in three ways:

#### Option A — From a Douyin hashtag page URL (recommended)

Open any hashtag page in a desktop browser. The URL ends with the numeric `ch_id`:

```
https://www.douyin.com/challenge/1575791821492238
                                  └──────── chId ────────┘
```

Copy the trailing number → paste it into the input field.

#### Option B — From a share / short URL

When someone shares a hashtag link on mobile, Douyin rewrites it into a short form. Paste the short URL into the address bar of a desktop browser and hit Enter — it redirects to the canonical `/challenge/<id>` form, then grab the trailing number as in Option A.

```
https://v.douyin.com/iJxxxxxxx/   →   https://www.douyin.com/challenge/1575791821492238
```

#### Option C — From a video inside the hashtag

Open any video that belongs to a hashtag. The URL contains the `aweme_id` (video id) — but you also need the `ch_id`. Click the hashtag chip below the video description; it opens the canonical hashtag page, then grab the ch\_id from the URL as in Option A.

#### Quick validation

After entering a `chId`, the upstream returns `cha_name` (the hashtag name). If `cha_name` is empty or null, the id is invalid — re-check the URL or pick another hashtag.

#### Common mistake

- ❌ **Do not** paste the share URL — only the trailing numeric id is accepted.
- ❌ **Do not** include `ch_id=` query-string form (`ch_id=1575791821492238`) — strip the `ch_id=` prefix.
- ✅ Correct: `"chId": 1575791821492238`
- ✅ Correct: `"chId": "1575791821492238"` (string form also accepted — both fields parse to integer internally)

### Use it together with the other Douyin Actors

This Actor is part of the 5-Actor Douyin MVP set. Use it together with:

| Where in the pipeline | Actor | Use it to |
|---:|---|---|
| you are here | **Douyin Hashtag Detail Scraper (you are here)** | (this Actor) |
| before / step ① | [Douyin Hashtag Search Scraper](../douyin-hashtag-search/README.md) | keyword search → get topic\_id (= ch\_id) for any hashtag you want to look up |
| sister step ③ | [Douyin Hashtag Video List Scraper](../douyin-hashtag-video-list/README.md) | walk the full video list under the same ch\_id |
| sister Actor | [Douyin Hot Search List Scraper](../douyin-hot-search-list/README.md) | board-level trends — find the topic in mainstream before it gets saturated |
| sister Actor | [Douyin Live Hot Search List Scraper](../douyin-live-hot-search-list/README.md) | live-stream specific trends |

**You are here:** **Douyin Hashtag Detail Scraper** — run this on its own for the upstream use case described above, or chain it with the other 4 Actors for a full Douyin keyword → hashtag → videos → trends pipeline.

### Use cases

| Persona | Use it for |
|---|---|
| Influencer marketer | Discover a hashtag's total reach (view\_count) before partnering with creators in that vertical |
| Brand manager | Monitor your brand-challenge's user\_count and view\_count to track momentum |
| Trend researcher | Map a challenge's metadata (cha\_name, desc) to category and growth phase |
| Content ops | Extract share\_url / share\_title to drive cross-platform UGC programs |
| Competitor analyst | Pull challenge metadata for any ch\_id you find in competitor video URLs |

### Why this Actor exists

Douyin's hashtag system is the primary discovery surface on the platform. Knowing a challenge's `view_count` and `user_count` is the first step in any influencer / brand / trend analysis workflow. This Actor is the **step ① entry point** of the 4-Actor Douyin MVP set.

### Pricing

Free users are limited to **5 runs per day**. Paid users (`APIFY_USER_IS_PAYING=1`) have unlimited runs. The Actor itself adds no markup — you pay the upstream provider per request plus the standard Apify compute unit cost.

### Test locally

```bash
cd douyin-hashtag-detail
UPSTREAM_API_KEY=... UPSTREAM_BASE_URL=<your-upstream-base-url> npm test
```

- `node test/unit.js` — 3 unit assertions on normalize / extract / rank.
- `node test/integration.js` — 1 live call against a known ch\_id.

### Output schema

See `.actor/output_schema.json` for the full type schema, or read it at runtime via the Apify API.

### License

MIT

# Actor input Schema

## `chId` (type: `string`):

Douyin challenge id (treated as string to preserve leading zeros in older IDs). Example: '1575791821492238'.

## Actor input object example

```json
{}
```

# Actor output Schema

## `dataset` (type: `string`):

One normalized dataset item per matched item. See output\_schema section of README for the per-actor item shape (topic\_id/ch\_id, hot\_value, engagement metrics, etc.).

## `summary` (type: `string`):

Run-level summary: input params (keyword / chId / boardType / etc.), requests, uniqueItems, itemsPushed, activeTime, tier (paid/free/free-unchecked), runsToday, dailyLimit, notes.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("opspilot.cc/douyin-hashtag-detail").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("opspilot.cc/douyin-hashtag-detail").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 '{}' |
apify call opspilot.cc/douyin-hashtag-detail --silent --output-dataset

```

## MCP server setup

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

```

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/eYRHVTNtbue1h3bvq/builds/EfP6egBIlT4sqrP8P/openapi.json