跳转到主要内容

​
概览

metrics 字段使开发者能够访问 Post 和媒体对象的公共与非公开互动度量。公共度量对任何拥有开发者账户的人员可用，非公开度量则可由自有/授权账户（定义见下文）访问。度量包括请求中指定的每条 Post 的展示次数总计、转发、Quote Tweets、like、回复、视频观看次数、视频观看四分位、URL 和个人资料链接点击次数。若该 Post 作为 Ad 投放，还可选择查看在自然或推广 context 中获得的度量细分。 公共度量可通过 App-only Token 认证请求。非公开度量只能为自有/授权的 Posts 请求，这意味着开发者需要使用 OAuth 2.0 或 OAuth 1.0a 的用户上下文授权进行认证。 非公开、自然与推广度量仅适用于在过去 30 天内创建的 Posts。

​
术语

  • 已授权账户：已通过授予访问其账户的权限来授权你的 X 开发者 App 的 X 账户（任一App 权限级别均可访问 Post 度量）。
  • 已关联账户：与你的 X 开发者 App 关联的 X 账户。
  • 公开度量：任何人都可在 X 上访问的总量，例如 like 数和转发（Retweet）数。
  • 非公开度量：不对公众在 X 上展示的总量，例如曝光次数和视频观看四分位。需要 OAuth 2.0 或 OAuth 1.0a 的用户上下文认证。
  • 自然度量：归属于自然 context（以常规方式发布和查看）的公开与非公开度量集合。需要 OAuth 2.0 或 OAuth 1.0a 的用户上下文认证。
  • 推广度量：归属于推广 context（作为 Ads 广告活动的一部分发布或查看）的公开与非公开度量集合。需要 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 被转发的总次数。不包括带评论的 Quote Tweets（“带评论的转发”）。要获得 X 客户端显示的“转发和评论”总数，请将 retweet_count 与 quote_count 相加。
Quote Tweetsdata.public_metrics.quote_count统计该 Post 被带新评论（消息）转发的总次数。付费场景不存在 Quote Tweets，因此所有 Quote Tweets 均为自然产生。
Likesdata.public_metrics.like_count, data.organic_metrics.like_count, data.promoted_metrics.like_count统计该 Post 被标记为 like 的总次数。为与 X 上公开显示的计数保持一致，public_metrics 字段返回来自自然与付费场景的 like 总数。
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 中包含的视频被观看的总次数。该数值为该视频在所有发布它的 Posts 中的观看次数总和。需要媒体扩展 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 及其附带视频的公开度量，使用如下 fields 和 expansions。请务必将 $BEARER_TOKEN 替换为你自己生成的 OAuth 2.0 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"
      }
    ]
  }
}
⌘I