Douyin Hashtag Video List Scraper

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 — the Actor's built-in upstream key is already configured.

Input

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 upstream request but push more items.

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

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 upstream 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."
}

Pagination

# 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.

How to find a chId

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.

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 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
UGC sourcer	Mine videos under a hashtag for top-performing content to remix or react to
Competitor analyst	Walk the full video list of a rival brand's challenge to spot trends and gaps
Influencer marketer	Pull the top videos under a vertical hashtag and reach out to the authors
Trend researcher	Sample the first 50-200 videos under a challenge to gauge the audience mix
Content ops	Export full video metadata + author profiles into your CRM

Why this Actor exists

Douyin challenges surface thousands to millions of videos. Walking them with the upstream 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.

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

cd douyin-hashtag-video-list
UPSTREAM_API_KEY=... UPSTREAM_BASE_URL=<your-upstream-base-url> npm test

Output schema

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

License

MIT