ログイン無料トライアルを開始
easyCoexistence 公式 API

TikTok 動画の指標を API で取得:再生数、視聴時間、完了率

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 は、Claude、ChatGPT、またはご自身のコードから get_social_insights を使って TikTok 動画の指標を読み取ります。

video.insights

視聴時間、完了率、維持率、流入元、視聴者の内訳に必要なスコープです。基本的な数値には video.list が必要です。

7 days

動画が非アクティブな期間です。この後は reach、視聴時間、流入元、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>"]}'

レスポンスはどのような形ですか?

投稿ごとに 1 つのオブジェクトを持つ videos 配列と、指定した fields の項目が返ります。ページングには cursor と has_more も含まれます。TikTok 自身の例を抜粋すると、単位がわかります。視聴時間は小数点以下 3 桁までの秒単位で、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:Follow フィードです。
  • Sound:サウンドページです。
  • Personal Profile:プロフィールページです。
  • Search:検索ページです。
  • Direct Message:ダイレクトメッセージです。TikTok Studio がアカウントのデータを表示する場合のみ該当します。
  • Others:その他すべてです。

視聴者の内訳はどのような種類がありますか?

4 種類あり、いずれもアカウントのフォロワーではなく、その投稿を視聴した人を説明します。いずれも 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 のビジネスアナリティクス由来のため、個人アカウントでは取得できず、上位のアカウントが必要です。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 を使います。object_id に動画の item_id を、metrics にフィールド名を渡すと、アカウントの最新 20 件の投稿の中から、その投稿のフィールドを返します。古い投稿の場合は、独自のコードが get_social_credentials のトークンを使い、fields と filters.video_ids をパラメータにして business/video/list/ を呼び出します。

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 で実現する

video_views、reach、full_video_watched_rate など取得したいフィールド名を指定し、動画の item_id を渡してください。古い投稿については、get_social_credentials がご自身のコードにアカウントのトークンを渡します。接続ごとに月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。

よくある質問

TikTok API では動画ごとの視聴時間を取得できますか?

はい。total_time_watched と average_time_watched は、video.insights スコープのトークンで /business/video/list/ から秒単位で返されます。

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 と必要な指標を指定してください。

続きを読む

最初のチャンネルを 2 分で接続しましょう。

プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。

  • 3 日間無料
  • いつでも解約可能
  • 公式 API のみ使用
  • 24/7 監視

確認日