Douyin Hashtag Video List Scraper

✨ What you get

EN — Get the video list of a Douyin hashtag by its numeric ch_id, with cursor-based pagination. Returns up to count videos per page (1-50) with full metadata: video id, description, cover URL, play URL, share URL, engagement counts (likes / shares / comments / plays), and author profile. Use the returned cursor + hasMore to walk the full list.

ZH — 抖音话题作品列表 — 通过 ch_id 抓取作品视频列表,支持 cursor 翻页。 每次返回最多 count 条(1-50):作品 ID、文案、封面、播放地址、分享链接、互动数据(点赞/分享/评论/播放)、作者资料。利用返回的 cursor + hasMore 可以拉完整个话题。

Built for viral-content mining, competitor research, UGC sourcing, influencer analytics, and trend monitoring on Douyin — China's #1 short-video platform.

5 free runs / day. No API key required — No API key or setup required.

💼 Use cases

• Sampling what actually ranks under a challenge — with chId plus sortType set to most-liked or latest, the rows show the videos creators are producing inside that topic, with digg_count, share_count, comment_count and play_count per item.
• Mining the top performers for remix or reaction content — the returned video_url, cover_url and share_url give you the assets and the source link for the videos worth responding to.
• Auditing a rival's challenge — walk the cursor and you get every video under a competitor's branded topic with author identity attached, which is the fastest read on how their volume is distributed.
• Building an outreach list from a topic — author.uid, author.nickname and author.avatar sit on each video row, so the creators posting under a vertical are a by-product of the crawl.

✅ Who this is for

• UGC and content sourcing teams — looking for material to react to, remix or brief against.
• Competitive and competitor analysts — who need a video-level view under a brand's own hashtag.
• Influencer marketers — identifying creators posting inside a vertical they want to buy.
• Trend researchers — sampling the audience mix on a challenge by walking the first pages.

❌ Who this is NOT for

• Anyone starting from a keyword — chId is required, and finding it is the same manual work described in the hashtag detail Actor. A keyword is the hashtag search Actor's job.
• Pushing count up for a fast harvest — count accepts 1-50, but the upstream warns to keep the default of 10 to avoid bugs. Treat page size as a small knob, not a bulk mode.
• One-shot export of a whole challenge — there is no bulk walk; you page by passing the returned cursor on the next run until hasMore flips to false. A large challenge is many sequential runs.
• Anything time-series — sortType is comprehensive / most-liked / latest and play_count is a cumulative lifetime counter on each video. Neither is a growth rate, and one run gives no history.
• Comment-level or hashtag-level questions — video rows carry engagement counters and author identity but no comment text, and the hashtag's own view_count / user_count live in the separate detail Actor.

📥 Input parameters

Field	Type	Required	Default	Notes
chId	string	yes	—	Douyin challenge id. Accept both numeric and string forms (defensive parsing).
cursor	integer	no	0	Pagination cursor. Start at 0; pass the returned cursor from the previous page.
sortType	integer	no	0	Sort order — 0 = comprehensive (default), 1 = latest, 2 = hottest.
count	integer	no	10	Page size (1-50). Larger pages cost the same Data provider request but push more items.

{
  "chId": "1575791821492238",
  "cursor": 0,
  "sortType": 0,
  "count": 10
}

The chId is the numeric challenge id Douyin assigns to every hashtag. See the dedicated guide in ../douyin-hashtag-detail/README.md#how-to-find-a-chid for the three methods (hashtag page URL, share URL redirect, video hashtag chip) and the common mistakes (do not paste the full URL or the ch_id= query-string form).

TL;DR: open the canonical hashtag page in a desktop browser →

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

Copy the trailing number. For this Actor, chId accepts both integer and string forms (1575791821492238 or "1575791821492238") — defensive parsing handles both.

📤 Output

The Actor pushes one item per video to the default dataset and writes a SUMMARY record with cursor, hasMore, and uniqueItems so you can resume pagination.

{
  "rank": 1,
  "aweme_id": "7400000000000000000",
  "desc": "一段关于深海世界的唯美视频 🎬",
  "create_time": 1725984000,
  "duration_ms": 30500,
  "video_url": "https://play.douyin.com/aweme/v1/play/?video_id=...",
  "cover_url": "https://p11-sign.douyinpic.com/cover.jpeg",
  "share_url": "https://www.iesdouyin.com/share/video/7400000000000000000",
  "engagement": {
    "digg_count": 123456,
    "share_count": 5678,
    "comment_count": 901,
    "play_count": 2345678
  },
  "author": {
    "uid": "user_id",
    "nickname": "深海摄影师",
    "avatar_url": "https://p11-sign.douyinpic.com/avatar.jpeg"
  },
  "rawData": { /* full Data provider aweme object */ }
}

SUMMARY record (key-value store):

{
  "ok": true,
  "chId": "1575791821492238",
  "cursor": 0,
  "nextCursor": 5,
  "hasMore": true,
  "requests": 1,
  "uniqueItems": 0,
  "note": "Pass nextCursor as input.cursor on the next run to paginate."
}

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

⚙️ How it works

# Page 1
apify call douyin-hashtag-video-list --input '{"chId":"1575791821492238","cursor":0,"count":10}'

# Page 2 — pass the nextCursor from the previous SUMMARY
apify call douyin-hashtag-video-list --input '{"chId":"1575791821492238","cursor":5,"count":10}'

Stop when hasMore flips to false.

💰 Billing

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 data provider provider per request plus the standard Apify compute unit cost.

📚 Resources

cd douyin-hashtag-video-list
Data provider_API_KEY=... Data provider_BASE_URL=<your-Data provider-base-url> npm test

MIT

📜 Notes & caveats

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 Video List Scraper (you are here)	(this Actor)
before / step ①	../douyin-hashtag-search/README.md	keyword search → get topic_id (= ch_id) for the hashtag you want to crawl
before / step ②	../douyin-hashtag-detail/README.md	get the ch_info (view_count, user_count, share info) for the same ch_id before crawling videos
sister Actor	../douyin-hot-search-list/README.md	board-level trends — discover rising boards whose videos you want to crawl
sister Actor	../douyin-live-hot-search-list/README.md	live-stream specific trends

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

Why this Actor exists

Douyin challenges surface thousands to millions of videos. Walking them with the data provider cursor protocol is the only way to do bulk analysis. This Actor is the step ② follow-up of the 4-Actor Douyin MVP set — pair it with douyin-hashtag-detail to go from challenge name to videos.