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

​
概要

metrics フィールドを使用すると、開発者は Post およびメディアオブジェクトの公開・非公開のエンゲージメント指標にアクセスできます。公開指標は developer account を持つユーザーなら誰でもアクセス可能で、非公開指標は所有/認可済みアカウント（定義は後述）からのみアクセス可能です。指標には、リクエストで指定した各 Post ごとのインプレッション数、Retweet、Quote Tweet、いいね、返信、動画再生数、動画視聴四分位、URL とプロフィールリンクのクリック数の合計が含まれます。さらに、その Post が Ad としてプロモーションされた場合、オーガニックまたはプロモーションのコンテキストで獲得した指標の内訳を表示するオプションもあります。 公開指標は App-only Token 認証でリクエストできます。非公開指標は所有/認可済みの Post に対してのみリクエストできるため、開発者は OAuth 2.0 または OAuth 1.0a のユーザーコンテキスト認可で認証する必要があります。 非公開、オーガニック、プロモーションの指標は、過去30日以内に作成された Post に対してのみ利用可能です。

​
用語

  • 承認済みアカウント: あなたのX アプリに、そのアカウントへのアクセス権を付与することで承認した X アカウント（どのアプリの権限レベルでも Post メトリクスへのアクセスが可能です）。
  • 所有アカウント: あなたのX アプリにリンクされた X アカウント。
  • 公開メトリクス: いいね数や Retweet 数など、X 上で誰でも参照できる合計値。
  • 非公開メトリクス: インプレッション数や動画視聴四分位など、X 上で一般公開されていない合計値。OAuth 2.0またはOAuth 1.0aのユーザーコンテキストによる認証が必要です。
  • オーガニックメトリクス: オーガニックなコンテキスト（通常の方法で投稿・閲覧）に起因する公開・非公開メトリクスの集合。OAuth 2.0またはOAuth 1.0aのユーザーコンテキストによる認証が必要です。
  • プロモーションメトリクス: プロモーションのコンテキスト（広告キャンペーンの一環として投稿・閲覧）に起因する公開・非公開メトリクスの集合。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 ユーザーコンテキストによる認証が必要です。
Retweetsdata.public_metrics.retweet_count, data.organic_metrics.retweet_count, data.promoted_metrics.retweet_countPost がリツイートされた回数。Quote Tweets（「コメント付きリツイート」）は含みません。X クライアントに表示される「Retweets and comments」の合計を取得するには、retweet_count と quote_count を合算してください。
Quote Tweetsdata.public_metrics.quote_countPost が新しいコメント（メッセージ）付きでリツイートされた回数。有料コンテキストからの Quote Tweets は存在しないため、すべての Quote Tweets はオーガニックです。
Likesdata.public_metrics.like_count, data.organic_metrics.like_count, data.promoted_metrics.like_countPost が「いいね」された回数。public_metrics フィールドは、X 上で公開表示される数値との整合性を保つため、オーガニックと有料の両方の合計「いいね」数を返します。
Repliesdata.public_metrics.reply_count, data.organic_metrics.reply_count, data.promoted_metrics.reply_countPost に返信された回数。public_metrics フィールドは、オーガニックと有料の両方の返信の合計数を返します。
URL Link Clicksdata.non_public_metrics.url_link_clicks, data.organic_metrics.url_link_clicks, data.promoted_metrics.url_link_clicksユーザーが Post 内の URL リンクまたは URL プレビューカードをクリックした回数。OAuth 1.0a ユーザーコンテキストによる認証が必要です。
User Profile Clicksdata.non_public_metrics.user_profile_clicks, data.organic_metrics.user_profile_clicks, data.promoted_metrics.user_profile_clicksPost の表示名、ユーザー名、プロフィール画像などの部分がクリックされた回数。OAuth 1.0a ユーザーコンテキストによる認証が必要です。
Video viewsincludes.media.public_metrics.view_count, includes.media.organic_metrics.view_count, includes.media.promoted_metrics.view_countPost に含まれる動画が再生された回数。これは、当該動画が投稿されたすべての Post にわたって集計された動画再生数です。メディアの拡張 expansions=attachment.media_keys が必要です。
Video view quartilesincludes.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 が必要です。

​
メトリクスの取得

​
Public Metrics

次のリクエストでは、Post と添付動画の公開メトリクスを、以下の fields と expansions で取得します。必ず $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": "test"
  },
  "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"
      }
    ]
  }
}