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	–	Apify or custom proxy. Residential proxy strongly recommended

Important: TikTok aggressively blocks datacenter IPs. Without a residential proxy the actor is likely to hit a CAPTCHA (Path 3). Use Apify's RESIDENTIAL proxy group or any rotating residential proxy.

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	否	–	代理配置，强烈建议使用住宅代理

注意：TikTok 对数据中心 IP 的封锁非常激进。不使用住宅代理时极易触发验证码（路径 3）。建议选择 Apify RESIDENTIAL 代理组，或任意旋转住宅代理。

本地调试

# 安装 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

成本参考

情况	用时	内存消耗
主路成功（无代理，本地）	~12s/hashtag	~400 MB
主路成功（住宅代理）	~15s/hashtag	~400 MB
DOM 兜底	~30s/hashtag	~400 MB

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