通过 API 获取 TikTok 视频指标:观看次数、观看时长与完播率
TikTok 商务 API 通过 GET /business/video/list/ 返回每条帖子的全生命周期指标,需在 fields 中按名称请求:video_views、reach、likes、comments、shares 和 favorites;以秒为单位的 total_time_watched 和 average_time_watched;full_video_watched_rate、video_view_retention、impression_sources,以及 audience_countries 等观众细分数据。大多数计数会延迟 24 至 48 小时才能获取,且在发布 365 天后停止更新。
easyCoexistence 通过 get_social_insights,让 Claude、ChatGPT 或您自己的代码读取 TikTok 视频的指标:指定所需字段,例如 video_views、reach 或 full_video_watched_rate,并提供视频的 item_id。
观看时长、完播率、留存率、流量来源和观众细分数据所需的权限范围为 video.insights;基础计数只需 video.list。
视频在一段时间不活跃后,其触达、观看时长、流量来源和 audience_countries 可能缺失。
视频的 audience_countries 与 audience_cities 列表中的大多数条目。
video_views、likes、reach、观看时长和流量来源的常见延迟,以 UTC 计。
一条视频有哪些指标?
GET /business/video/list/ 为 fields 中指定的每条帖子返回这些指标,按帖子的整个生命周期汇总,而不是账户指标的 60 天窗口。观看次数和点赞等计数需要访问令牌具备 video.list 权限,而观看、完播率和留存数据需要 video.insights:
如何请求这些指标?
在 fields 中指定它们,这是一个 JSON 数组;只要列出了一个以上的字段,数组中就必须包含 item_id。您可以用 filters.video_ids 选择帖子。若不设置该过滤条件,端点会翻页返回账户的帖子,每次最多 20 条:
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","video_views","reach","video_duration","total_time_watched","average_time_watched","full_video_watched_rate","impression_sources","audience_countries"]' \
--data-urlencode 'filters={"video_ids":["<ITEM_ID>"]}'响应是什么样的?
返回一个 videos 数组,每条帖子对应一个对象,包含所请求的字段;另外还有用于翻页的 cursor 和 has_more。下面是 TikTok 官方示例(已删减),展示了单位:观看时长以秒为单位,最多保留三位小数;full_video_watched_rate 为小数,此例中为 0.0237:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"video_views": 1231,
"reach": 154,
"likes": 10,
"comments": 2,
"shares": 0,
"video_duration": 20.0,
"total_time_watched": 695.942,
"average_time_watched": 4.118,
"full_video_watched_rate": 0.0237,
"impression_sources": [
{ "impression_source": "For You", "percentage": 0.8983 },
{ "impression_source": "Personal Profile", "percentage": 0.0904 },
{ "impression_source": "Follow", "percentage": 0.0113 }
],
"audience_countries": [
{ "country": "US", "percentage": 0.7574 },
{ "country": "GB", "percentage": 0.1775 }
]
}
],
"cursor": 0,
"has_more": false
}
}流量来源是什么意思?
impression_sources 按占比从大到小排列观众发现该帖子的渠道,每一项是一个 impression_source,附带其百分比。TikTok 记录了以下取值:
- For You:For You 推荐信息流。
- Follow:关注信息流。
- Sound:声音页面。
- Personal Profile:个人主页。
- Search:搜索页面。
- Direct Message:私信,仅当 TikTok Studio 为该账户显示此类数据时才有。
- Others:其他所有来源。
有哪些观众细分数据?
共四项,均描述观看该帖子的人,而非账户的粉丝,且都需要 video.insights 权限:
audience_genders:按性别划分的观众占比,Female、Male 或 Other。audience_countries:最多 10 个国家或地区,使用 ISO 3166-1 alpha-2 代码。audience_cities:最多 10 个城市,格式如 US Cincinnati。audience_types:NEW_VIEWER与RETURN_VIEWER,以及FOLLOWER_PERCENT对比NON_FOLLOWER_PERCENT。
哪些指标取决于账户类型?
少数点击和主页访问来自 TikTok Business Analytics,需要的不只是个人账户。profile_views(帖子带来的主页访问)需要具备 Advanced Access 权限的账户或 Verified Business Account。website_clicks、phone_number_clicks、lead_submissions、app_download_clicks、email_clicks 和 address_clicks 需要 Verified Business Account。
为什么指标可能缺失或延迟?
TikTok 大多在离线状态下计算这些指标,且仅依据 TikTok Analytics 的数据。计数和观看指标通常延迟 24 至 48 小时,而 item_id、caption 和 links 是实时的。对于 7 天内无人观看、点赞、评论或分享的视频,reach、观看时长、流量来源和 audience_countries 可能缺失。TikTok 的建议是与该视频互动,并在 24 至 48 小时后重试。数据在发布 365 天后停止更新;因违规行为(例如音乐版权问题)被过滤的帖子则不会返回。
easyCoexistence 如何读取视频的指标?
通过 get_social_insights:将视频的 item_id 作为 object_id 传入,并将字段名称作为 metrics 传入。它会返回该帖子的字段,并在账户最近 20 条帖子中查找。对于较早的帖子,由您自己的代码以 fields 和 filters.video_ids 作为参数调用 business/video/list/,令牌来自 get_social_credentials。
get_social_insights {
"account_id": "<ACCOUNT_ID>",
"object_id": "<ITEM_ID>",
"metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}常见错误
- 假设所有百分比使用同一刻度。TikTok 的示例中 impression_sources 以加起来等于 1 的小数表示,而其 audience_cities 示例中的数值如 17.4921。
- 请求多个字段却不带 item_id。TikTok 的参考文档警告此类请求可能失败。
- 期望一条久未互动的旧视频仍有触达数据。7 天内若无观看、点赞、评论或分享,TikTok 可能会将触达、观看时长和流量来源留空。
- 将帖子指标与账户的每日指标进行比较。帖子的数据涵盖其整个生命周期,而账户指标按天提供,最长可追溯 60 天。
对于较早的帖子,get_social_credentials 会向您自己的代码提供该账户的令牌。每个连接每月 US$ 9 起,连接越多越便宜,最低降至 US$ 0.75,首 3 天免费试用。
常见问题
TikTok API 能按视频返回观看时长吗?
可以。total_time_watched 和 average_time_watched 以秒为单位,来自 /business/video/list/,访问令牌需具备 video.insights 权限范围。
如何通过 API 获取 TikTok 视频的完播率?
在 /business/video/list/ 的 fields 中请求 full_video_watched_rate。TikTok 将其定义为观看视频至结束的观众所占的百分比。
为什么我的 TikTok 视频的触达和观看时长为空?
若视频在过去 7 天内没有观看、点赞、评论或分享,TikTok 可能会省略这些数据;而近期数据有 24 至 48 小时的延迟。
API 能否返回某一条特定 TikTok 视频的指标?
可以。将其 ID 放在 filters.video_ids 中,并在 fields 中填写 item_id 及所需指标。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间