登入開始免費試用
easyCoexistence 官方 API

透過 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.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 或已驗證商業帳戶。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 提供的權杖。

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 監察

驗證日期