登录开始免费试用
easyCoexistence 官方 API

通过 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.insights;基础计数只需 video.list。

7 days

视频在一段时间不活跃后,其触达、观看时长、流量来源和 audience_countries 可能缺失。

10

视频的 audience_countries 与 audience_cities 列表中的大多数条目。

24 to 48 h

video_views、likes、reach、观看时长和流量来源的常见延迟,以 UTC 计。

一条视频有哪些指标?

GET /business/video/list/ 为 fields 中指定的每条帖子返回这些指标,按帖子的整个生命周期汇总,而不是账户指标的 60 天窗口。观看次数和点赞等计数需要访问令牌具备 video.list 权限,而观看、完播率和留存数据需要 video.insights:

video_viewsViews, counted on the first playback in an impression session
reachPeople who watched the post at least once
likes, comments, sharesLifetime totals; shares include sends to friends inside TikTok
favoritesTimes the post was added to favorites
total_time_watchedSeconds viewers spent watching, in total
average_time_watchedAverage seconds viewers spent watching
full_video_watched_rateShare of viewers who finished the video
video_view_retentionShare of viewers still watching at each second
impression_sourcesWhere viewers found the post, by share
new_followersViewers who started following the account
engagement_likesShare of viewers who liked at each second
video_durationLength of the video in seconds

如何请求这些指标?

在 fields 中指定它们,这是一个 JSON 数组;只要列出了一个以上的字段,数组中就必须包含 item_id。您可以用 filters.video_ids 选择帖子。若不设置该过滤条件,端点会翻页返回账户的帖子,每次最多 20 条:

Metrics for one video
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:

A video's metrics, from TikTok's example
{
  "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。

One video's metrics through MCP
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 天。
使用 EasyCoexistence 完成这些操作

对于较早的帖子,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 监控

验证时间