TikTok Hashtag Stats Actor

Language / 语言: English · 中文

---

English

What it does

Scrapes exact TikTok hashtag-level summary statistics — video count and total view count — using Playwright.

The actor opens https://www.tiktok.com/tag/<hashtag> in a headless Chromium browser and intercepts the /api/challenge/detail XHR that TikTok fires automatically on page load. This XHR carries challengeInfo.statsV2.videoCount and statsV2.viewCount as exact integers (e.g. 1 403 431 633 800), far more precise than the abbreviated text shown on-screen ("1.4T views").

How it works

Browser opens https://www.tiktok.com/tag/<hashtag>
        │
        ├─► Path 1 (primary)
        │   XHR /api/challenge/detail intercepted
        │   └─ statsV2.videoCount  ← exact integer  ✓
        │   └─ statsV2.viewCount   ← exact integer  ✓
        │
        ├─► Path 2 (DOM fallback — XHR not triggered)
        │   Read visible page text:
        │   [data-e2e="challenge-vvcount"]    → view_count  (e.g. "1.4T views")
        │   [data-e2e="challenge-item-count"] → video_count (e.g. "100M videos")
        │   Values are approximate (K/M/B/T rounded)
        │
        └─► Path 3 (failure)
            CAPTCHA or network error — error field is set

Output fields

Field	Type	Description
hashtag	string	Canonical hashtag name from TikTok
platform	string	Always "tiktok"
challenge_id	string	TikTok internal challenge ID
video_count	integer|null	Total number of videos
view_count	integer|null	Total cumulative view count
description	string	Hashtag description text
is_commerce_hashtag	bool	Whether it is a commerce/branded hashtag
share_meta_desc	string	Short share description
_source	string	Code path that produced the result
error	string|null	Non-null only on failure

Example output

{
  "hashtag": "roblox",
  "challenge_id": "159721",
  "platform": "tiktok",
  "video_count": 100049186,
  "view_count": 1403431633800,
  "description": "Explore and find your own favourite way to play with #Roblox!",
  "is_commerce_hashtag": false,
  "share_meta_desc": "Watch awesome short videos created with trending hashtag #roblox",
  "_source": "Playwright /api/challenge/detail statsV2"
}

Input

Field	Required	Default	Description
hashtags	Yes	–	Array of hashtag names (without #), e.g. ["roblox", "minecraft"]
proxyConfiguration	No	Direct Apify cloud egress	Optional Apify or custom proxy. The default does not use a proxy or a residential proxy group.
maxConcurrency	No	2	Number of hashtags processed in parallel.
xhrTimeoutSecs	No	6	Seconds to wait for /api/challenge/detail before DOM fallback.
pageLoadTimeoutSecs	No	18	Page navigation timeout.
domTimeoutSecs	No	2	DOM fallback selector timeout.
blockResources	No	true	Block images, media, fonts, and stylesheets to reduce browser time.

Proxy behavior: If no proxy is selected, the actor uses direct Apify cloud egress and does not automatically switch to RESIDENTIAL. If you explicitly select RESIDENTIAL, the actor respects that input.

Local development

# Install CLI
npm install -g apify-cli

# Create local input
mkdir -p storage/key_value_stores/default
echo '{"hashtags":["roblox","minecraft"]}' > storage/key_value_stores/default/INPUT.json

# Run locally (no Docker, no proxy)
pip install apify playwright
playwright install chromium
apify run --purge

Deploy to Apify

apify login
apify push

---

中文

功能说明

使用 Playwright 抓取 TikTok hashtag 级别的汇总数据，输出精确到个位的视频数（video_count）和累计播放量（view_count）。

Actor 用无头 Chromium 浏览器打开 https://www.tiktok.com/tag/<hashtag>，拦截 TikTok 页面自动发出的 /api/challenge/detail XHR 请求。该 XHR 返回的 challengeInfo.statsV2 包含精确整数（例如 1 403 431 633 800），远比页面上显示的缩写文字（"1.4T views"）精确。

工作流程

浏览器打开 https://www.tiktok.com/tag/<hashtag>
        │
        ├─► 路径 1（主路）
        │   成功拦截 XHR /api/challenge/detail
        │   └─ statsV2.videoCount  ← 精确整数  ✓
        │   └─ statsV2.viewCount   ← 精确整数  ✓
        │
        ├─► 路径 2（DOM 兜底 — XHR 未被触发）
        │   读取页面可见文字：
        │   [data-e2e="challenge-vvcount"]    → view_count  (如 "1.4T views")
        │   [data-e2e="challenge-item-count"] → video_count (如 "100M videos")
        │   数值为 K/M/B/T 近似值
        │
        └─► 路径 3（失败）
            遭遇验证码或网络错误，error 字段非空

输出字段说明

字段	类型	说明
hashtag	string	TikTok 返回的 hashtag 规范名称
platform	string	固定为 "tiktok"
challenge_id	string	TikTok 内部 challenge ID
video_count	integer|null	该 hashtag 下的视频总数
view_count	integer|null	累计总播放量
description	string	hashtag 描述文字
is_commerce_hashtag	bool	是否为商业/品牌 hashtag
share_meta_desc	string	分享简介文字
_source	string	数据来源路径标识
error	string|null	失败时非空，成功时为 null

示例输出（roblox）

{
  "hashtag": "roblox",
  "challenge_id": "159721",
  "platform": "tiktok",
  "video_count": 100049186,
  "view_count": 1403431633800,
  "description": "Explore and find your own favourite way to play with #Roblox!",
  "is_commerce_hashtag": false,
  "share_meta_desc": "Watch awesome short videos created with trending hashtag #roblox",
  "_source": "Playwright /api/challenge/detail statsV2"
}

输入参数

参数	必填	默认值	说明
hashtags	是	–	hashtag 名称列表（不含 #），例如 ["roblox", "minecraft"]
proxyConfiguration	否	Apify 云端直连出口	可选 Apify 或自定义代理。默认不启用代理，也不使用住宅代理组。
maxConcurrency	否	2	并行处理的 hashtag 数量。
xhrTimeoutSecs	否	6	等待 /api/challenge/detail 的秒数，超时后进入 DOM 兜底。
pageLoadTimeoutSecs	否	18	页面导航超时时间。
domTimeoutSecs	否	2	DOM 兜底选择器等待时间。
blockResources	否	true	阻断图片、视频、字体和样式表，降低浏览器耗时。

代理行为：用户没有选择代理时，actor 使用 Apify 云端直连出口，并且不会自动切换到 RESIDENTIAL。如果用户明确选择 RESIDENTIAL，actor 会尊重这个输入。

本地调试

# 安装 Apify CLI
npm install -g apify-cli

# 创建本地输入文件
mkdir -p storage/key_value_stores/default
echo '{"hashtags":["roblox","minecraft"]}' > storage/key_value_stores/default/INPUT.json

# 本地运行（无 Docker，无代理）
pip install apify playwright
playwright install chromium
apify run --purge

部署到 Apify

apify login
apify push

成本参考

情况	用时	内存消耗
主路成功（热启动，非住宅云端直连）	~6-12s/hashtag	~500-900 MB
DOM 兜底	~10-18s/hashtag	~500-900 MB
多 hashtag 并发	取决于 maxConcurrency	建议 1024-2048 MB

Apify 平台按实际计算单元（CU）计费，单个 hashtag 预计消耗 0.04–0.08 CU。