メインコンテンツへスキップ

​
概要

metrics フィールドにより、開発者は Post およびメディアオブジェクトの公開・非公開のエンゲージメント metrics にアクセスできます。公開 metrics はデベロッパーアカウントを持つすべての人が利用でき、非公開 metrics は所有/許可済みアカウント（定義は下記）からのみアクセス可能です。metrics には、リクエストで指定された各 Post のインプレッション、リツイート、Quote Tweets、like、返信、動画再生数、動画再生クォータイル、URL およびプロフィールリンクのクリック数の合計が含まれます。Post が広告として配信された場合、オーガニックまたはプロモーションの context で獲得した metrics の内訳を表示するオプションもあります。 公開 metrics は App-only Token 認証でリクエストできます。非公開 metrics は所有/許可済みの Posts に対してのみリクエスト可能であり、開発者は OAuth 2.0 または OAuth 1.0a のユーザーコンテキスト認可で認証する必要があります。 非公開、オーガニック、プロモーションの metrics は、過去 30 日以内に作成された Posts に対してのみ利用可能です。

​
用語

  • 認可済みアカウント: あなたのX developer appに、そのアカウントへのアクセスを許可したXアカウント（どのapp permission levelでもPostのmetricsへアクセス可能）。
  • 所有アカウント: あなたのX developer appにリンクされたXアカウント。
  • 公開metrics: X上で誰でも参照できる合計値（例: like数、リツイート数）。
  • 非公開metrics: X上で一般には公開されない合計値（例: インプレッション数、動画視聴四分位）。利用にはOAuth 2.0またはOAuth 1.0aのユーザーコンテキスト認証が必要。
  • オーガニックmetrics: オーガニックなcontext（通常の投稿・閲覧）に紐づく公開・非公開metricsのグループ。利用にはOAuth 2.0またはOAuth 1.0aのユーザーコンテキスト認証が必要。
  • プロモーションmetrics: プロモーションのcontext（広告キャンペーンの一環として投稿・閲覧）に紐づく公開・非公開metricsのグループ。利用にはOAuth 2.0またはOAuth 1.0aのユーザーコンテキスト認証に加え、そのPostが広告でプロモーションされている必要がある。

​
利用可能なメトリクス

指標API 表現説明
Impressionsdata.non_public_metrics.impression_count, data.organic_metrics.impression_count, data.promoted_metrics.impression_countPost が閲覧された回数（ユーザー単位のユニークではありません）。Post の一部でも画面に表示されれば 1 回としてカウントされます。OAuth 1.0a ユーザーコンテキスト認証が必要です。
リツイートdata.public_metrics.retweet_count, data.organic_metrics.retweet_count, data.promoted_metrics.retweet_countPost がリツイートされた回数。Quote Tweets（「コメント付きリツイート」）は含まれません。X クライアントに表示される「リツイートとコメント」の合計を取得するには、retweet_count と quote_count を合算してください。
Quote Tweetsdata.public_metrics.quote_countPost が新しいコメント（メッセージ）付きでリツイートされた回数。広告配信（有料）コンテキストでの Quote Tweets は存在しないため、すべてオーガニックです。
いいねdata.public_metrics.like_count, data.organic_metrics.like_count, data.promoted_metrics.like_countPost が「like」された回数。public_metrics フィールドは、X 上で公開される表示と整合するよう、オーガニックおよび有料コンテキストの「like」の合計値を返します。
返信data.public_metrics.reply_count, data.organic_metrics.reply_count, data.promoted_metrics.reply_countPost に返信された回数。public_metrics フィールドは、オーガニックおよび有料コンテキストの合計値を返します。
URL リンククリックdata.non_public_metrics.url_link_clicks, data.organic_metrics.url_link_clicks, data.promoted_metrics.url_link_clicksユーザーが Post 内の URL リンクまたは URL プレビューカードをクリックした回数。OAuth 1.0a ユーザーコンテキスト認証が必要です。
ユーザープロフィールクリックdata.non_public_metrics.user_profile_clicks, data.organic_metrics.user_profile_clicks, data.promoted_metrics.user_profile_clicksユーザーが Post の一部（表示名、ユーザー名、プロフィール画像）をクリックした回数。OAuth 1.0a ユーザーコンテキスト認証が必要です。
動画再生数includes.media.public_metrics.view_count, includes.media.organic_metrics.view_count, includes.media.promoted_metrics.view_countPost に含まれる動画が再生された回数。これは、当該動画が含まれるすべての Posts を横断して集計した再生数です。メディアの拡張 expansions=attachment.media_keys が必要です。
動画視聴クォータイルincludes.media.non_public_metrics.playback_0_count, includes.media.non_public_metrics.playback_25_count, includes.media.non_public_metrics.playback_50_count, includes.media.non_public_metrics.playback_75_count, includes.media.non_public_metrics.playback_100_count動画の各クォータイル到達まで再生したユーザー数。OAuth 1.0a ユーザーコンテキスト認証とメディアの拡張 expansions=attachment.media_keys が必要です。

​
metrics をリクエストする

​
公開metrics

次のリクエストでは、Postおよび添付動画の公開metricsを、以下のfieldsとexpansionsを使用して取得します。$BEARER_TOKEN は自身で生成した Bearer Token に置き換えてください。
  • tweet.fields=public_metrics
  • expansions=attachments.media_keys&media.fields=public_metrics

​
サンプルリクエスト

curl 'https://api.x.com/2/tweets?ids=1204084171334832128&tweet.fields=public_metrics&expansions=attachments.media_keys&media.fields=public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'

​
非公開メトリクス（非公開・オーガニックメトリクス）

次のリクエストでは、Post および添付動画に関する非公開メトリクスに加え、オーガニックメトリクスの詳細も取得します。これらの fields は X 上で一般には閲覧できない非公開情報のため、リクエストには OAuth 2.0 または OAuth 1.0a のユーザーコンテキスト認証が必要です。以下で必要となる OAuth 1.0a の署名生成については、当社のガイドを参照してください。
  • tweet.fields=non_public_metrics,organic_metrics
  • expansions=attachments.media_keys&media.fields=non_public_metrics,organic_metrics

​
リクエスト例

curl 'https://api.x.com/2/tweets/1204084171334832128?tweet.fields=non_public_metrics,organic_metrics&media.fields=non_public_metrics,organic_metrics&expansions=attachments.media_keys' --header 'authorization: OAuth oauth_consumer_key="CONSUMER_API_KEY", oauth_nonce="OAUTH_NONCE", oauth_signature="OAUTH_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="OAUTH_TIMESTAMP", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​
サンプル応答

{
  "data": {
    "attachments": {
      "media_keys": ["13_1204080851740315648"]
    },
    "id": "1263145271946551300",
    "non_public_metrics": {
      "impression_count": 956,
      "url_link_clicks": 9,
      "user_profile_clicks": 34
    },
    "organic_metrics": {
      "impression_count": 956,
      "like_count": 49,
      "reply_count": 2,
      "retweet_count": 9,
      "url_link_clicks": 9,
      "user_profile_clicks": 34
    },
    "text": "テスト"
  },
  "includes": {
    "media": [
      {
        "media_key": "13_1204080851740315648",
        "non_public_metrics": {
          "playback_0_count": 0,
          "playback_100_count": 1,
          "playback_25_count": 2,
          "playback_50_count": 1,
          "playback_75_count": 1
        },
        "organic_metrics": {
          "playback_0_count": 0,
          "playback_100_count": 1,
          "playback_25_count": 2,
          "playback_50_count": 1,
          "playback_75_count": 1,
          "view_count": 1
        },
        "type": "video"
      }
    ]
  }
}
⌘I