跳转到主要内容

​
概览

metrics 字段允许开发者访问 Post 和媒体对象的公开与非公开互动指标。公开指标对任何拥有开发者账号的用户可见，非公开指标仅对自有/已授权账号（定义见下文）可见。可用指标包括请求中每条 Post 的曝光次数、转发（Retweet）、引用转发（Quote Tweet）、点赞、回复、视频播放次数、视频播放分位数、URL 点击和个人资料链接点击的总数。若该 Post 作为广告投放，还可以选择查看自然与付费场景下的指标拆分。 公开指标可通过 App-only Token 进行认证请求。非公开指标仅可针对自有/已授权的 Post 请求，这意味着开发者需要使用 OAuth 2.0 或 OAuth 1.0a 的用户上下文授权进行认证。 非公开、自然与付费指标仅适用于最近 30 天内创建的 Post。

​
术语

  • 已授权账户：通过授予你的 X 开发者应用 访问其账户的权限而完成授权的 X 账户（任何应用权限级别都可访问 Post 指标）。
  • 已绑定账户：与你的 X 开发者应用 关联的 X 账户。
  • 公开指标：任何人都可在 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_count统计该 Post 被查看的次数（不按用户去重）。当 Post 的任意部分在屏幕上可见时即计为一次查看。需要 OAuth 1.0a 用户上下文认证。
Retweetsdata.public_metrics.retweet_count, data.organic_metrics.retweet_count, data.promoted_metrics.retweet_count统计该 Post 被转发（Retweet）的次数。不包含引用推文（“带评论的转发”）。要获得 X 客户端上显示的“转发和评论”总数，请将 retweet_count 与 quote_count 相加。
Quote Tweetsdata.public_metrics.quote_count统计该 Post 被带新评论（消息）转发的次数。不存在付费场景下的引用推文，因此所有引用推文均为自然产生。
Likesdata.public_metrics.like_count, data.organic_metrics.like_count, data.promoted_metrics.like_count统计该 Post 被点赞的次数。为与 X 上公开显示的计数保持一致，public_metrics 字段返回来自自然与付费场景的点赞总数。
Repliesdata.public_metrics.reply_count, data.organic_metrics.reply_count, data.promoted_metrics.reply_count统计该 Post 被回复的次数。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_clicks统计用户点击 Post 中以下元素的次数：显示名称、用户名、头像。需要 OAuth 1.0a 用户上下文认证。
Video viewsincludes.media.public_metrics.view_count, includes.media.organic_metrics.view_count, includes.media.promoted_metrics.view_count统计该 Post 中包含的视频被观看的次数。该数值会在所有包含该视频的 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。

​
请求度量

​
公开指标

在以下请求中，我们将获取 Post 及其附带视频的公开指标，使用如下字段和 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 及其所附视频获取非公开指标，并提供有关自然指标的更多详细信息。由于这些字段为私有，且在 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"
      }
    ]
  }
}