透過 API 查看 TikTok 影片指標:播放次數、觀看時間與完整觀看率
TikTok 的 API for Business 會透過 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 可讓 Claude、ChatGPT 或你自己的程式碼,透過 get_social_insights 讀取 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 或已驗證商業帳戶。website_clicks、phone_number_clicks、lead_submissions、app_download_clicks、email_clicks 與 address_clicks 則需要已驗證商業帳戶。
為何指標可能缺失或延遲?
因為 TikTok 大多離線計算這些指標,且只來自 TikTok Analytics。計數與觀看指標通常延遲 24 至 48 小時,而 item_id、文案與連結則為即時。若某影片 7 天內無人觀看、點讚、評論或分享,覆蓋人數、觀看時間、流量來源與 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 監察
驗證日期