跳转到主要内容

​
概览

Enterprise 这是仅在我们的托管访问等级内提供的 Enterprise 级 API。要使用此 API，您必须先与我们的企业销售团队开立账户。 了解更多 Engagement API 提供对 Post 的展示与互动度量的访问。尽管大多数度量和 endpoint 需要使用 OAuth 1.0a 用户上下文进行身份验证，您仍可通过 OAuth 2.0 Bearer Token 与 /totals endpoint 访问公开的“收藏”“转发”“回复”和“视频观看次数”等度量。   注意： 您可能会发现 X 某些网页控制台中报告的数据与 Engagement API 报告的数据之间存在差异。出现这种差异的原因在于，网页控制台通常只显示在所选时间范围内发生的互动和/或展示。例如，网页控制台可能显示某个日历月内对 Posts 的互动，而 Engagement API 可能显示超出该月份但仍在请求时间范围内的互动。在这些情况下，应以 Engagement API 为准。  

​
请求 endpoints

Engagement API 提供三个 endpoints：

​
当前总计：[/totals]

  • 请求会返回所需 Posts 的展示次数和互动次数的总度量
  • 仅限以下度量：Impressions、Engagements、Favorites、Replies、Retweets、Quote Tweets 和 Video Views
  • 支持使用 OAuth 1.0a 用户上下文，检索在过去 90 天内创建的 Posts 的 Impressions 和 Engagements 度量
  • 支持使用 OAuth 2.0 Bearer Token 检索任意 Post的 Favorites、Retweets、Quote Tweets、Replies 和 Video Views 度量
  • 结果基于发起请求时的当前展示次数和互动次数总计
  • 适用于驱动仪表板报告，并在多个 @handles 间计算互动率
  • 每次请求最多可为 250 个 Posts 请求度量  

​
最近 28 小时：[/28hr]

  • 请求可返回展示次数的总度量、互动的总度量，以及过去 28 小时内各项互动度量的明细
  • 数据可按 Post ID 分组，并可按时间序列汇总，按天或按小时查看
  • 适用于跟踪新近创建内容的表现
  • 支持所有可用度量
  • 支持在单次请求中为最多 25 个 Posts 获取度量  

​
历史：[/historical]

  • 请求可返回过去一年内的展示量、互动量，以及各类单项互动度量的细分，基于互动发生时间（而非 Post 创建时间）。
  • 请求支持开始日期和结束日期参数，可灵活限定最长 4 周的特定时间范围。
  • Post 互动数据最多仅可回溯 365 天。
  • 数据可按 Post ID 分组，或按时间序列汇总，按日或按小时聚合。
  • 非常适合用于将近期表现与历史基准对比评估，或构建某个 @handle 的历史表现概览。
  • 支持所有可用的度量。
  • 支持每次请求最多为 25 个 Post 请求度量。

​
可用度量

下表介绍了可通过 Engagement API 访问的度量类型。 请参阅我们的度量解读页面，以进一步了解下述度量。
度量Endpoint 可用性需要用户上下文描述
impressions全部是Post 被查看次数的统计。此度量仅适用于过去 90 天内发布的 Post。
engagements全部是用户与 Post 互动次数的统计。此度量仅适用于过去 90 天内发布的 Post。
favorites全部是 - /28hrs & /Historical

否 - /totals		Post 被收藏次数的统计。
retweets全部是 - /28hrs & /Historical

否 - /totals		Post 被转发次数的统计。
quote_tweets/totals否 - /totalsPost 被引用转发（也称为引用）次数的统计。
replies全部是 - /28hrs & /Historical

否 - /totals		Post 被回复次数的统计。
video_views全部是 - /28hrs & /Historical

否 - /totals		指定 Post 中的视频 50% 可见区域持续至少两秒的观看次数统计。

视频观看次数仅适用于 1800 天内的 Post。如果您尝试请求超过 1800 天的 Post 的视频观看次数，您将在响应中收到以下对象，以及包含您请求的其他度量的单独对象：

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

请注意： 您可能会发现 X 自有平台（移动应用和网站）中显示的视频观看次数度量与您通过 /28hr 和 /historical endpoint 获得的数字之间存在差异。

_ X 用户界面和 /totals endpoint 中显示的视频观看次数将显示指定视频在所有包含该视频的 Post 中的聚合观看次数。这意味着 UI 中显示的度量包括该视频被转发或在其他 Post 中重新发布时的所有观看次数。此度量不包括 gif 的视频观看次数。
_ /28hr 和 /historical endpoint 提供的视频观看次数仅包括您正在获取度量的特定 Post 产生的观看次数。此度量不包括 gif 的视频观看次数。
media_views/28hr /historical是您的媒体内容（包括视频、gif 和图像）的所有观看次数（自动播放和点击）统计。
media_engagements

(原名 Media Clicks)		/28hr /historical是Post 中的媒体内容（如图像或视频）被点击次数的统计。
url_clicks/28hr /historical是Post 中的 URL 被点击次数的统计。
hashtag_clicks/28hr /historical是Post 中的话题标签被点击次数的统计。
detail_expands/28hr /historical是Post 被点击以查看详细信息的次数统计。
permalink_clicks/28hr /historical是Post 的永久链接（该 Post 的专用网页）被点击次数的统计。
app_install_attempts/28hr /historical是从该 Post 触发的 App 安装事件次数统计
app_opens/28hr /historical是从该 Post 触发的 App 打开事件次数统计。
email_tweet/28hr /historical是Post 通过电子邮件分享次数的统计。
user_follows/28hr /historical是用户（Post 作者）通过该 Post 被关注次数的统计。
user_profile_clicks/28hr /historical是用户（Post 作者）的个人资料通过该 Post 被点击次数的统计。

​
互动分组

分组用于自定义组织返回的互动度量。每个请求最多可包含 3 个分组。您可以按以下一个或多个值对度量进行分组： 三个 endpoint 均支持：
  • tweet.id
  • engagement.type  
“/28hr”和“/historical”可提供时间序列度量，因此支持：
  • engagement.day
  • engagement.hour
要进一步了解分组，请访问指南部分中的Engagement API Grouping页面。

​
指南

​
开发者快速入门指南

​
介绍

本指南旨在为开发者提供与 Engagement API 集成的入门说明。我们将先讨论集成的“原因”，随后再深入讲解技术层面的“实现方式”细节。
Engagement API 提供了什么？
  • Engagement API 为任何已授权你的 App 使用三方 OAuth（3-legged OAuth）代其请求度量的 X 账户，提供该账户在过去 90 天内所发布并拥有的 Posts 的曝光与互动数据。这个功能强大且易于集成的解决方案，可即时获取曝光以及深度互动数据，例如 URL 点击、#hashtag 点击等。
  • Engagement API 为任意 Post 提供点赞、转发、Quote Tweets、回复以及视频观看次数等的总计汇总度量。这是获取任意单个 Post 或 Post 集合基础互动数据的有力方式。
  • Engagement API 通过允许客户使用 15+ 项性能度量有效衡量内容表现，为社交聆听、营销与发布平台带来新的价值，从而衡量在 X 上的 ROI。
  • Engagement API 是请求/响应式 API，允许应用开发者发送包含 Post ID、所需度量以及时间范围的请求，API 会即时返回 data。  
为什么要集成？示例用例
  • 了解你内容的总体触达，看看有多少人查看。了解有多少人观看视频、点击链接、点击话题标签或安装我的 App。
  • 生成总量与时间序列的互动度量。
  • 了解任何公开 Post 的基本互动度量（likes、转发、Quote Tweets、replies）。
  • 利用这些度量来判断哪些类型的 Post 表现更好，从而我可以更高频地发布，获得更多曝光和互动。
  • 当我的任一 Post 达到 100 like 或其他阈值时，自动化营销行为（如从另一个自有账号转发内容）。
  • 将我的各个活动相互对标与比较，用于 A/B 测试。
  • 分析哪些类型的内容更能满足客服部门的需求，以确定如何以及何时回应。
  • 展示从我的平台发布内容的分析数据。  
The Engagement API was launched in 2016 and was the first X API to provide these in-depth engagement metrics at scale. The Engagement API is easy to use and enables customers to automate the process. Here is a case study describing an example integration: 现在我们已经探讨了 Engagement API 的“缘由”，接下来开始深入技术细节。

​
集成 Engagement API

API 简介
Engagement API 是一个简单的 RESTful API，它接收以 JSON 编码的请求，并以 JSON 编码的参与度度量进行响应。请求由三个主要部分组成（请参阅链接了解更多文档）：
  • Post ID 的数组。
  • 指定感兴趣度量类型的数组。类型包括 “impressions”、“retweets”、“hashtag_clicks” 和 “user_follows” 等。
  • 参与度分组，这是一个 JSON 结构，用于指示你希望在 API 响应中如何组织参与度数据。
在许多情况下，Engagement Types 和 Groupings 在不同请求之间会相对固定，只有 Post ID 会更新。 Engagement API 提供了三个 endpoint：
  • Totals - 提供 Post 的参与度总计。部分度量对所有 Post 可用，另一些仅提供过去 90 天的数据。
  • 28 hour - 提供过去 28 小时的时间序列参与度度量。
  • Historical - 为自 2014 年 9 月 1 日以来发布的 Post 提供最长连续四周的时间序列参与度度量。
/totals endpoint 支持每次请求最多为 250 个 Post 获取度量。/28hour 和 /historical endpoints 支持 每次请求 25 个。 在讨论如何获取 Engagement API 的访问权限之后，我们将演示如何发起 API 请求，提供 OAuth 概览，并附上其他技术资源的链接。
获取 API 访问权限
如果你正在阅读本文档，你很可能已经获得了 Engagement API 的访问权限。否则，请联系你的 Enterprise 客户经理，或在此处申请 Enterprise 访问。 第一步是通过开发者门户，使用已获批准的开发者账户创建一个 X App。你的客户经理需要该应用关联的数值型 App id 以授予访问权限。如果你需要申请开发者账户，可在此处进行申请。
发起请求
好消息是，向 Engagement API 发起请求很简单。这个请求中，我们将针对以下两条 @XDevelopers 的 Post，获取转发（Retweet）、引用推文（Quote Tweet）、收藏（Favorite）和回复的总数：
1/ Today we’re sharing our vision for the future of the X API platform
https://t.co/XweGngmxlP
 — Twitter Dev (@TwitterDev) April 6, 2017
Don’t miss the Posts about your Post. Now on iOS, you can see Retweets with comments all in one place. pic.x.com/oanjZfzC6y — X (@X) May 12, 2020
第一步是使用 JSON 构造 API 请求，其中包含这两个 Post ID 的数组、一个感兴趣的互动类型数组，以及一个自定义命名的“groupings” JSON 对象，用于指示我们希望在响应中如何组织度量。以下是我们的请求示例： 
{
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}
要获取这些总计度量，我们会将此 JSON 请求通过 POST 发送到 https://data-api.x.com/insights/engagement/totals endpoint。 我们将添加以下请求头，表明请求使用 JSON 编码，并采用 Gzip 压缩（请求正文可能会较大）：
  • Content-Type: application/json
  • Accept-Encoding: gzip  
发起请求时，我们使用 OAuth 进行身份验证，下一节将作进一步说明。 该 API 返回如下负载： 
{
  "grouping name": {
    "1260294888811347969": {
      "favorites": "17111",
      "quote_tweets": "3254",
      "replies": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favorites": "492",
      "quote_tweets": "66",
      "replies": "42",
      "retweets": "324"
    }
  }
}
请注意，响应中的度量按“groupings”定义所描述的结构组织：先按 Post ID 列出度量，在下一层再按互动类型分组。 这很简单。如果你是首次使用 OAuth 进行身份验证，请查看下一节。

​
使用 OAuth 进行认证

OAuth 是技术行业中非常常见的认证标准。如果你已经在使用 OAuth（例如与其他 X API 搭配），你很可能在使用某种特定语言的 OAuth 库来屏蔽繁琐细节。如果你是 OAuth 新手，请访问我们的 OAuth with the X API 页面，或直接前往 https://oauth.net 了解更多。随后，我们建议你为所用的集成语言选择一个合适的 OAuth 库并从那里入手。使用这些库进行认证的典型流程通常包括：配置你的密钥和令牌，创建一个 HTTP 对象，然后使用该对象发起请求。 例如，在 Ruby 生态中，以下伪代码演示了如何使用 Ruby 的 ‘oauth’ gem 构建一个启用 OAuth 的 App，并发起 POST 请求： 
require 'oauth'

#组装 JSON 请求（如上所述）。
request = make_json_request()

#使用我的 App 消费者密钥和密钥构建 App 消费者对象。
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => 'https://data-api.x.com'})
#使用提供权限的账户所提供的令牌构建用户令牌。如果进行仅限 App 的请求（使用 /totals endpoint 检查不需要权限的 Tweets），可以跳过此步骤。
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#创建启用 OAuth 的 App 对象。
app = OAuth::AccessToken.from_hash(consumer, token)
#发出 POST 请求。
result = app.post("/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})
Engagement API 同时支持仅应用和用户上下文两种身份验证方式。如果你使用 /totals endpoint 为非自有的公开 Post 收集参与度度量，则无需用户授权，你可以使用仅应用方式进行身份验证。在这种情况下，你只需使用你的 app key 和 secret 进行认证。 OAuth 也允许 App 使用与用户关联的令牌“代表另一位用户”发起 API 请求。如果你为自有 Post 生成 Engagement 度量，即由你持有其用户令牌的用户发布的 Post，你将以用户上下文发起请求，这意味着需要同时使用你的 app keys 和特定用户的 access tokens 进行身份验证。这些用户 access tokens 通常通过“Sign-in with X”流程提供，或直接由用户提供（请注意，若直接从用户处获取令牌，必须使用 twurl）。一旦用户提供了其令牌，这些令牌不会过期，并且可与 Engagement API 配合使用以代表该用户发起请求；只要用户未重置令牌或更改密码即可。若发生上述情况，用户需要向你提供新的令牌。 你可以通过此表查看不同度量所需的身份验证方式。

​
选择 Engagement API 的 endpoint

Engagement API 提供三个不同的 endpoint：
  • Totals - 提供来自“owned”或“unowned” Posts 的所选度量的总汇。一些度量适用于所有 Posts，另一些仅适用于过去 90 天内发布的 Posts。每个请求最多支持 250 个 Posts。
  • 28 hour - 为过去 28 小时内的“owned” Posts 提供时间序列的 Engagement 度量。每个请求最多支持 25 个 Posts。
  • Historical - 为自 2014 年 9 月 1 日以来发布的“owned” Posts 提供最长连续四周的时间序列 Engagement 度量。每个请求最多支持 25 个 Posts。  
每个 endpoint 都有其独特特性。无论你计划同时使用这三个，还是在权衡哪个更符合你的用例，理解它们之间的差异都很重要。 下面我们将介绍一些关键概念，进一步探讨这三个 endpoint，并给出与特定 endpoint 大体对应的示例用例。我们希望这些信息能帮助你更高效地集成这三个 endpoint，或帮助你确定哪一个最契合你的目标。  

​
关键概念

以下几个关键概念有助于阐明三个 Engagement API endpoint 的不同功能以及它们提供的 data。  
展现与互动度量
“展现”表示某条 Post 在 X 平台自然情境下被查看的次数。在推广或付费情境中看到的 Posts 所产生的展现不计入其中。在 Engagement API 推出之前，Post 的展现仅代表潜在的查看次数，其计算基于作者账号及所有转发该内容账号的关注者数量，并未考虑用户实际上可能并未看到该 Post 的常见情况。 由 Engagement API 生成的展现度量反映的是 Post 实际被渲染用于展示的次数。如果某位你的关注者错过了你的 Post，则不计为一次展现。 Engagement API 提供 14 种独立的互动度量，metric types，每一种都代表用户在看到一条 Post 时可以采取的一个具体操作。这些包括转发、like、回复、点击诸如 #hashtags、链接和媒体等实体、关注作者，以及查看作者的个人资料。上述所有单独操作都会汇总为一个 Engagements 度量。
自有与非自有 X 内容
Engagement 明确区分自有与非自有 Post。自有 Post 指由你的账户发布的 Post，或你已获授权可请求其 Engagement 数据的 Post。与其他 X API 相同，你可通过让其他 X 用户/账户共享 access token，以便代表他们发起 API 请求来获得授权。获取这些令牌的常见方式是使用“使用 X 登录”流程。 /totals endpoint 为自有与非自有 Post 都提供参与度数据。对于非自有 Post，你可以请求在 Post 展示中公开可见的参与度度量：Favorite、转发（Retweet）和 Reply。对于这些度量，Engagement API 的价值在于能够以自动化方式大规模获取。对于自有 Post，/totals endpoint 还提供 Impression 和（总）Engagement 度量。 /28hr 和 /historical endpoints 仅提供自有 Post 的度量，这意味着在对这些 endpoints 发起请求时，你必须传递用户 context。
总计与时间序列互动数据
/‌totals endpoint 顾名思义，仅提供各类互动的总计值。这些数值表示自 Post 发布以来的最新累计总数。如果某个 Post 刚发布，而你反复请求其 metrics，这些总计通常会在每次请求时发生变化。 /‌28hr 和 /‌historical endpoints 可同时提供总计与时间序列数据。请求时间序列数据时，互动度量可汇总为按天或按小时的数据。   请参阅我们关于互动分组的文档，了解如何使用 /‌28hr 和 /‌historical endpoints 请求时间序列数据。

​
endpoint 与示例用例

鉴于上文讨论的特性与差异，每个单独的 endpoint 通常对应不同类型的用例。为帮助你判断哪个 endpoint 最适合你的具体用例，下面提供一些示例用户表述及相应的最佳匹配 endpoint。
/totals
  • 我只需访问部分指标类型（Impressions、Engagements、Favorites、Retweets、Quote Tweets、Replies 和 Video Views）。
  • 我需要获取任意 Post 的基础互动数据，而不仅限于我拥有的 Posts。
  • 我想将表现与竞争对手进行对比。
  • 我想跟踪某个话题标签或活动（包含我不拥有的 Posts）的基础互动统计。
  • 我不需要按天或按小时拆分的数据，只需在发起请求时获取当前总量。
  • 我需要一个可在报告或仪表板中展示的单一指标，并且不打算存储任何数据。
  • 我想在页面加载时展示数据，只需发起请求并接收响应。
  • 我需要每天获取数十万到数百万条 Posts 的数据。  
/28hr
  • 我需要访问全部 17 种度量类型。
  • 我想展示最近 28 小时内发布的 Post 的数据。
  • 我有一个每天运行一次的作业来获取我关心的 data，并且只需要获取过去一天的数据。
  • 我需要按天或按小时拆分的度量。
  • 我想在仪表板中按小时展示活动的时间序列分解。
  • 我需要对每天数十万条 Post 提供高访问能力。
  • 我具备存储能力，可以每天刷新一次 data，并持续累积统计。  
/historical
  • 我需要访问全部 17 种度量类型。
  • 我需要获取可追溯至 2014 年 9 月创建的 Post 的历史数据。
  • 我希望展示用于比较不同投放活动的详细历史分析。
  • 我需要按天或按小时细分度量。
  • 我不需要对 Engagement API 的高访问级别，每天只需为几百到上千条 Post 获取数据。

​
Engagement API 关键特性

  • RESTful API 提供 JSON 数据，支持带有 JSON 请求体的 POST 请求。
  • 请求类型： 客户端应用可以发起以下类型的请求：
    • 总互动量（Total engagements） — 向 /totals endpoint 发送 HTTP POST 请求
    • 过去 28 小时互动量（Last 28-hour engagements） — 向 /28hr endpoint 发送 HTTP POST 请求
    • 历史互动量（Historical engagements） — 向 /historical endpoint 发送 HTTP POST 请求
  • OAuth 身份验证：
    • OAuth 1.0a 用户上下文：对于通过 三方 OAuth 授权你 App 的用户所拥有的 Posts，可获取所有可用度量。发起请求时，必须使用该用户的 Access Tokens。
    • OAuth 2.0 Bearer Token：任何公开的 Post 均可获取部分度量（转发、引用 Tweet、回复、收藏和视频观看次数）。
  • 请求 metadata 与结构：请求 data 是一个 JSON 对象，由 Post ID 数组、互动类型数组以及互动分组结构组成。
  • 每次请求包含的 Posts 数量：
    • /totals endpoint：250 个 Post ID
    • /28hr endpoint：25 个 Post ID
    • /historical endpoint：25 个 Post ID
  • 互动度量可用性：
    • /totals — 自 Post 发布起的度量总计。Impressions 和 Engagements 适用于过去 90 天内发布的 Posts，而转发、引用 Tweet、回复、收藏和视频观看次数适用于所有 Posts。
    • /28hr — 自请求时间起的最近 28 小时。
    • /historical — 自 2014 年 9 月 1 日起的任意 28 天区间。
  • 度量类型： 每个请求都包含一个 Metric Types 数组。其可用性取决于所用 endpoint；如果请求 /totals endpoint，还取决于 Posts 是否具备用户授权。
    • /totals endpoint：
      • 所有 Posts：收藏、转发、引用 Tweet、回复和视频观看次数
      • 需要 OAuth 1.0a 用户上下文：Impressions、Engagements、收藏、回复和转发
    • /28hr 和 /historical endpoints（需要 OAuth 1.0a 用户上下文并使用 Post 所有者的 Access Token）：Impressions、Engagements、收藏、回复、转发、URL 点击、Hashtag 点击、详情点击、Permalink 点击、媒体点击、App 安装尝试、App 打开、Post 邮件、视频观看次数和媒体观看次数
  • 互动分组： 每个请求都包含一个 Engagement Groupings 数组。通过这些分组，你可以自定义返回度量的组织方式。每个请求最多可包含三个分组。度量可按以下值组织：
    • 所有 endpoints：Post ID、Engagement Type
    • /28hr 和 /historical endpoints：如指定以下额外分组，这些 endpoints 将提供时间序列：Engagement Day、Engagement Hour
  • 集成期望： 你的团队将负责以下事项：
    • 创建并维护一个客户端应用，能够向 Engagement API 发送 HTTP 请求，并返回请求中所含 Post ID 的互动度量。
  • 限制
  • 视频观看次数仅适用于发布时间不超过 1800 天的 Posts。

​
使用 Engagement API 进行身份验证

请注意： 在您开始使用 API 之前，X 需要为您的开发者 App 启用对 Engagement API 的访问。为此，请务必将您计划用于身份验证的 App ID 提供给您的客户经理或技术支持团队。
Engagement API 提供两种身份验证方法：OAuth 1.0a 和 OAuth 2.0 Bearer Token。 OAuth 2.0 Bearer Token（也称“application-only”）允许访问公开可用的互动度量。使用此方法，在调用 /totals endpoint 时，可获取任何公开可见 Post 的 Favorites（亦称 Likes）、转发、Quote Tweets、回复以及视频观看次数的总计数。 OAuth 1.0a（也称“用户上下文”）允许您代表某个用户发送请求，并访问该用户的私有互动度量。 此身份验证方法适用于：
  • 发送至 /28hr endpoint 和 /historical endpoint 的所有请求
  • 访问以下任一私有度量：Impressions、Engagements、Media Views、Media Engagements、URL Clicks、Hashtag Clicks、Detail Expands、Permalink Clicks、App Install Attempts、App Opens、Email Post、User Follows 和 User Profile Clicks
当使用 OAuth 1.0a 发送请求时，您需要包含拥有相关 Post 或受保护资源的用户的 Access Tokens（Access Token 和 Secret）。如果在请求受保护的用户数据时未提供正确的用户 Access Tokens，Engagement API 将返回 403 Forbidden 错误。 即使您代表拥有这些 Post 的用户进行身份验证，Engagement API 也不允许您获取受保护的 Posts 的互动数据。尝试这样做将返回 400 Bad Request 错误，错误消息为 "Tweet ID(s) are unavailable"。 如果您代表自己的 X 账户（换言之，拥有开发者 App 的账户）发送请求，您可以在开发者门户中该开发者 App 的“Keys and tokens”选项卡下直接生成所需的 Access Tokens。 如果您代表其他任何用户发送请求，您需要使用三方 OAuth 授权流程以获取所需的 Access Tokens。以下文档包含更多相关说明：OAuth 1.0a: how to obtain a user’s access tokens。 如需更多示例（包括如何使用 OAuth 1.0a 进行身份验证），请参阅 X Developers 提供的 Engagement API Python 示例代码。

​
Engagement API 的最新变更

Engagement API 提供了极其重要的曝光与互动度量，帮助你监控在 X 上的活动表现。为持续支持基于我们数据的营销决策，我们很高兴分享 Engagement API 的最新变更，以在整个 X 的度量中实现更高的一致性。   我们近期部署了变更，使 Engagement API 采用与 X 分析仪表板（analytics.x.com）相同的度量聚合方法。为尽量减少在推出这些新度量时对 API 的破坏性影响，我们已于 2017 年 10 月 9 日部署了第一批变更。这些变更提升了你或你的客户在各个渠道监控 X 表现时的一致性。请参阅下方详细变更概览：
MetricChange
engagements我们已更新计入 overall engagements 的度量，以与 Post 分析仪表板保持一致。Engagements 衡量“人们与此 Post 互动的次数”。

对于包含媒体（如视频或 GIF）的 Posts，engagements 度量将不再包含媒体观看量。媒体观看量现可通过新的度量 media_views 获取。
media_clicks*此度量已被名为“media_engagements”的新度量取代。
video_views自 2018 年 7 月 6 日起，此度量可通过 /totals endpoint 获取“非自有” Posts 的数据。这意味着你可以使用仅 App 认证访问所有 Posts 的视频观看量。 

你只能请求 1800 天以内的视频观看量。如果尝试请求 1800 天之前的 Post 的视频观看量，你将收到如下返回：

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

请注意，它与 media_views 不同：video_views 遵循 MRC 标准，即至少有 50% 的视频处于可视区域且持续至少两秒。

**另外，请注意，你可能会看到 X 自有平台（移动 App 与网站）上显示的视频观看量，与通过 /28hr 与 /historical endpoints 获取的数值之间存在差异。

 X 用户界面中显示并通过 /totals endpoint 提供的视频观看量，是将某个视频在所有发布该视频的 Posts 中的观看量进行聚合。也就是说，UI 中的度量包含该视频在任何被转发或在其他独立 Posts 中再次发布的实例所产生的合并观看量。
 /28hr 与 /historical endpoints 提供的视频观看量仅包含你为其拉取度量的特定 Post 所产生的观看量。
media_views包括你媒体在视频、vines、gifs 与图片上的所有观看（自动播放与点击）。

请注意，带图片的 Posts 在分析仪表板中不显示 media_views 度量，但在 Engagement API 中会返回。
media_engagements*包括你媒体在视频、vines、gifs 与图片上的点击次数。此度量取代 media_clicks。
quote_tweets自 2020 年 7 月 7 日起，此度量可通过 /totals endpoint 获取“非自有” Posts 的数据。这意味着你可以使用仅 App 认证访问所有 Posts 的引用 Post 计数。

​
解读度量

注意： 你可能会注意到，某些 X 网页端仪表板上报告的数据与 Engagement API 报告的数据存在差异。造成这种差异的原因是，网页端仪表板通常只显示在所选时间范围内发生的互动和/或展示次数。例如，某个网页端仪表板可能仅展示某一日历月内对 Posts 的互动，而 Engagement API 可能会显示超出该月份范围但仍在你请求的时间范围内的互动。在这些情况下，应以 Engagement API 为准。  

​
展示量与互动数据

Engagement API 提供“自然”展示量与互动数据。 展示量表示某条 Post 在 X 平台的自然场景中被查看的次数。在推广或付费场景中看到的 Posts 所产生的展示量不计入统计。 互动表示某条 Post 在自然和推广两种场景下被观众产生互动的次数。互动包括但不限于：转发、收藏、回复、URL 点击、话题标签点击、提及点击，以及媒体观看。完整的互动行为列表请参阅 Engagement Data 部分。 要计算基准互动率，请在所分析的时间范围内，用某条 Post 的互动总数除以其展示量总数。 仅可检索自有 @handle 的 Posts，或已授权你的应用查看其 Post 详情的 @handle 的 Posts 的展示量与互动数据。Engagement API 会在内部跟踪针对合同约定的 @handle 上限所请求的唯一 @handle 数量。建议在整个月内也在客户端侧跟踪 @handle 请求用量。  

​
视频度量

在 X 中，有几种不同的度量用于表示媒体的曝光。首先是我们的视频观看（video views）度量，其遵循 MRC 标准：至少有两秒钟内，视频画面有 50% 处于可视区域。其次是 Media Views，它包含跨视频、Vine、GIF 和图片的所有媒体观看（自动播放与点击）。 视频观看度量适用于自有的 Posts，可通过 /28hour 和 /historical endpoint 获取；同时也适用于所有非自有的 Posts，可通过 /totals endpoint 获取。  虽然 X 用户界面中的视频观看度量也采用相同的 MRC 标准，但请注意，X 自有平台（移动 App 和网站）中显示的视频观看度量与您通过不同 Engagement API endpoint 获得的数值之间，可能存在差异。
  • /totals endpoint 与 X 用户界面提供的视频观看会显示某个给定视频在所有包含该视频的 Posts 中的聚合观看次数。这意味着，通过 /totals 提供并在 X UI 中显示的度量包含该视频在被转发（Retweet）或在其他独立 Posts 中再次发布时的合并观看次数。
  • /28hour 和 /historical Engagement API endpoint 提供的视频观看仅包含由您拉取度量的特定 Post 所产生的观看。   
请注意，我们不提供超过 1800 天的 Posts 的视频观看数据。作为替代，我们会返回一个对象，列出超过 1800 天的 Posts。对于您请求的 Posts，您仍将在单独的对象中收到所有其他度量。以下是一个响应示例： 
{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}
Media Views 指标仅适用于自有的 Post，并且仅在 /28hour 和 /historical endpoint 中可用。

​
Engagement API 分组

分组用于自定义组织返回的互动度量。每个请求最多可包含 3 个分组。你可以按以下一个或多个值对度量进行分组： 以下三个 endpoint 均支持：
  • tweet.id
  • engagement.type  
/28hr 和 /historical 可提供时间序列度量，因此还支持：
  • engagement.day
  • engagement.hour
分组按顺序生效，因此你可以通过调整 group_by 值的顺序来改变期望的结果格式。包含四个 group_by 值的分组仅支持以下两种格式之一： 
"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]
或 
"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]
例如，如果你想生成各指标类型的总计，请在请求中包含以下“groupings”规范（有关构建请求的更多信息，请参见 API Reference 页面）： 
{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "总计": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}
通过这种分组方式，Engagement API 的 JSON 响应会在根级包含一个名为 “Grand Totals” 的属性，其中按度量类型给出总计： 
{
  "总计": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}
要为单个 Post 生成按 Post ID 分组的 4 小时时序度量，以下分组规范将作为请求的一部分： 
{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}
通过此分组，Engagement API 的 JSON 响应将在根级包含一个 “Tweets_MetricType_TimeSeries” 属性，其中的度量数据先按 Post ID、再按度量类型细分，并附带对应的按小时时间序列： 
{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

​
常见问题

Enterprise

​
Engagement API

通过 Enterprise 订阅可获得 Engagement API 的访问权限。请填写此表单以联系销售团队。
如果你的合同对可与 Engagement API 搭配使用的唯一 handle 数量设有限制，X 的内部系统会跟踪使用 Engagement API 查询的、其 Post 被检索到的已认证用户的数量。客户也应在客户端记录该唯一数量。目前没有用于检查 Engagement API 的 @handle 使用情况的 usage API 或 UI。如果请求的 @handle 数量超过合同约定，系统不会阻止超额使用。在计费月末，查询到的唯一 @handle 数将与合同约定数量进行比对，并按合同条款收取超额费用。
目前没有用于检查 Engagement API 的 @handle 使用情况的 usage API 或 UI。如果请求的 @handle 数量超过合同约定，系统不会阻止超额使用。在计费月末，查询到的唯一 @handle 数将与合同约定数量进行比对，并按合同条款收取超额费用。为什么有效负载中返回的 engagements metadata 字段不等于各项参与度指标之和？这是预期行为。engagements metadata 字段未必总与 API 返回的各个参与度指标之和一致，因为它可能包含在有效负载中未被单独拆分的其他参与事件。换言之，将各项参与度指标相加的总数，可能不等于有效负载中返回的 engagements 指标字段的值。可以将 engagements metadata 字段理解为对该 Post 的任意点击或交互。  当 Post 实际没有 URL 时，为何有效负载中的 url_clicks 字段仍返回一个数字？这可能是因为包含类似 hashtag（会生成指向其他页面的链接）的 Post，如果被用户点击，也会计为一次 URL 点击。  
可能有多种原因导致你无法检索某个特定 Post 的参与数据，包括：
  • 你请求的 Post ID 不在你所用认证令牌代表第三方检索数据的权限范围内。
  • 你为 /totals endpoint 请求的 Post ID 不在过去 90 天内，因此无法返回展示量或参与度指标。
  • 你请求的 Post ID 已不可用，通常表示该内容已被删除或因其他原因不再公开可见。
请查阅在上述任一情况下你可能收到的不同错误消息。
当你向 Engagement API 发起请求时，可使用响应头中的 x-per-minute-limit 和 x-per-minute-remaining 信息来监控你的用量。x-per-minute-limit 表示你的配额，x-per-minute-remaining 表示你剩余的可调用次数。

​
错误排查指南

请务必查看我们关于使用 Engagement API 进行身份验证的指南。
[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]
在尝试对 /totals endpoint 进行身份验证时，请确保不要使用任何 access tokens 或 secrets。原因是，如果包含这些令牌且尝试拉取与这些令牌无关联的 Post 的内容，很可能会收到如下错误：
[
    Forbidden to access tweets: 1054424731825229824;
]

​
仍然没找到所需内容？

请联系技术支持，我们会尽快回复您。

​
API 参考文档

​
POST insights/engagement

​
方法

方法说明
POST /insights/engagement/totals获取一组 Tweets 的总展示次数和互动次数。
POST /insights/engagement/historical获取一组 Tweets 在最长 4 周内（可追溯至 2014 年 9 月 1 日）的展示次数和互动次数。
POST /insights/engagement/28hr获取过去 28 小时内一组 Tweets 的展示次数和互动次数。

​
身份验证

Engagement API 要求使用 HTTPS，并同时支持 User Context 和 Application-Only OAuth。对 Engagement API 的大多数请求需要使用 3-Legged OAuth（User Context 的一种特定形式），这意味着你需要使用已由你的 Twitter 客户经理为 Engagement API 访问注册并批准的 App 的 consumer key 和 secret，以及 Tweet 所有者的 access token 和 access token secret 来调用该 endpoint。以下请求需要此类 OAuth：
  • 任何对 /totals 的请求，用于获取 Impressions 和 Engagements 指标类型（仅限自有 Tweets）
  • 任何对 /28hr 的请求
  • 任何对 /historical 的请求
对 Engagement API 的某些请求可以使用 Application-Only OAuth，这意味着你只需提供 consumer key 和 secret，或 Bearer Token。以下请求可以使用此类 OAuth 执行：
  • 任何对 /totals 的请求，用于获取 Favorites、Replies、转发 或 Video Views 指标类型，且可针对任意 Tweet 检索
对于任何请求，你需要在 developer.x.com 的应用管理控制台中设置一个 Twitter App 及对应的 API Key。 请注意：如果你已在 developer.x.com 上登录你的 Twitter 账户，你可以通过 Twitter app dashboard 查看和编辑你现有的 Twitter apps。 设置好 App 后，需要你的客户代表批准该 app id，之后你的 App 才能向 Engagement API 发起请求。Access Tokens 必须用于表示“当前用户”，代表其他用户发起的请求必须使用有效令牌签名。请确保在准备 OAuth 签名基字符串之前，已在 URL 和 POST 请求体中妥当地对保留字符进行编码。 有关如何开始使用 OAuth 的更多信息，请访问以下链接：

​
POST /insights/engagement/totals

该 totals endpoint 支持一次性为最多 250 条 Tweets 的集合获取当前的总曝光次数和总互动次数。
请求方法HTTP POST
URLhttps://data-api.x.com/insights/engagement/totals
内容类型application/json
压缩Gzip。要使用 Gzip 压缩发送请求，请在连接请求中发送 Accept-Encoding 标头。
标头应如下所示：

Accept-Encoding: gzip
POST 格式请求可以作为 POST 请求发送，其中请求体是包含 Tweet ID 集合和所需分组的 JSON 对象。POST 格式为包含 tweets、engagements 和 groupings 对象的数组。每个请求最多可包含 250 个 Tweet ID。

示例 POST 请求体如下：


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“favorites”,
“quote_tweets”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
Tweet ID包含要查询互动数据的 Tweet ID 的数组。请注意，您只能请求由认证 @handle 创建的 Tweet 的数据。每个请求最多可包含 250 个 Tweet，且 Tweet ID 必须表示为字符串。
互动类型包含要查询的互动度量类型的数组。Totals endpoint 仅支持以下互动类型：impressions、engagements、favorites、retweets、quote_tweets、replies、video_views。
/totals endpoint 支持检索过去 90 天内创建的 Tweet 的 impressions 和 engagements，以及任何 Tweet 的 favorites、retweets、quote_tweets、replies 和 video_views。
分组Engagement API 的结果可以按不同的组返回，以最适合您的需求。每个请求最多可包含 3 个分组。

对于每个分组，您可以定义自定义分组名称，以便在应用程序中更容易引用此分组类型。

定义分组名称后，您可以选择按 tweet.id 和/或 engagement.type 分组。

分组按顺序执行，因此您可以通过更改 group_by 值的顺序来更改所需的结果格式。显示按 Tweet ID 和度量类型分隔的度量的示例分组如下：


“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
POST 大小限制一次最多可为 250 个 Tweet ID 发送请求。
响应格式JSON。您的请求标头应为响应指定 JSON 格式。
请求速率限制您将按分钟进行请求速率限制，具体根据您的访问级别在合同中指定。
示例请求（公共度量）curl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: Bearer ’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1070059276213702656”,“1021817816134156288”,“1067094924124872705”
],
“engagement_types”: [
“favorites”,“retweets”,“replies”,“quote_tweets”,“video_views”
],
“groupings”: {
“perTweetMetricsUnowned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
—verbose
—compressed
示例请求curl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1060976163948904448”,“1045709644067471360”
],
“engagement_types”: [
“favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements”
],
“groupings”: {
“perTweetMetricsOwned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}’
—verbose
—compressed
示例响应（公共度量）{
“perTweetMetricsUnowned”: {
“1021817816134156288”: {
“favorites”: “530”,
“quote_tweets”: “79”,
“replies”: “147”,
“retweets”: “323”,
“video_views”: “0”
},
“1067094924124872705”: {
“favorites”: “1360”,
“quote_tweets”: “29”,
“replies”: “56”,
“retweets”: “178”,
“video_views”: “5754512”
},
“1070059276213702656”: {
“favorites”: “69”,
“quote_tweets”: “5”,
“replies”: “7”,
“retweets”: “26”,
“video_views”: “0”
}
}
}
响应示例{
“perTweetMetricsOwned”: {
“1045709644067471360”: {
“engagements”: “2”,
“favorites”: “0”,
“impressions”: “47”,
“replies”: “0”,
“retweets”: “8”,
“quote_tweets”: “5”,
“video_views”: “0”
},
“1060976163948904448”: {
“engagements”: “4”,
“favorites”: “0”,
“impressions”: “148”,
“replies”: “1”,
“retweets”: “9”,
“quote_tweets”: “2”,
“video_views”: “0”
}
}
}
不可用的 Tweet ID对于包含已不可用 Tweet ID（例如已被删除）的查询，系统将为所有可用的 Tweet ID 返回相应数据，不可用的 Tweet ID 将在名为 unavailable_tweet_ids 的数组中列出。例如：

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: “26”,
“quote_tweets”: “2”
}
}
}

​
POST /insights/engagement/28hr

28 小时 endpoint 可用于在过去 28 小时内获取最多 25 条 Tweets 的曝光量与互动数据。该 endpoint 还支持请求所有受支持的各项度量。有关受支持度量的完整列表，请参阅 Metric Availability。
请求方法HTTP POST
URLhttps://data-api.x.com/insights/engagement/28hr
内容类型application/json
压缩Gzip。要使用 Gzip 压缩发送请求，请在连接请求中发送 Accept-Encoding 标头。
标头应如下所示：

Accept-Encoding: gzip
POST 格式请求可以作为 POST 请求发送，其中请求体是包含 Tweet ID 集合和所需分组的 JSON 对象。POST 格式为包含 tweets、engagements 和 groupings 对象的数组。每个请求最多可包含 25 个 Tweet ID。

示例 POST 请求体如下所示：


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
Tweet ID包含要查询互动数据的 Tweet ID 的数组。请注意，您只能请求由身份验证 @handle 创建的 Tweet 的数据。28 小时 endpoint 每个请求最多支持 25 个 Tweet，且 Tweet ID 必须表示为字符串。
互动类型要查询的互动度量类型的数组。

对于 28 小时 endpoint，支持 impressions、engagements 和所有单独的互动类型作为度量。有关支持的互动度量的完整列表，请参阅互动数据。
分组互动 API 的结果可以按不同的组返回，以最好地满足您的需求。每个请求最多可包含 3 个分组。

对于每个分组，您可以定义自定义分组名称，以便在应用程序中更容易引用此分组类型。定义分组名称后，您可以选择按以下一个或多个值进行分组：
tweet.id
engagement.type
engagement.day
engagement.hour
分组按顺序执行，因此您可以通过更改 group_by 值的顺序来更改所需的结果格式。一个按 Tweet ID、度量类型分隔度量的示例分组如下所示：

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


具有 4 个 group_by 项的分组仅在使用以下两个顺序之一时有效。在单个分组中具有 4 个 group_by 项但不是以下之一的请求将返回错误。此外，每个请求只允许一个具有 4 个 group_by 项的分组。

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
POST 大小限制一次最多可为 25 个 Tweet ID 发出请求。
响应格式JSON。您的请求标头应为响应指定 JSON 格式。
请求速率限制您将按分钟受到请求速率限制，具体如合同中根据您的访问级别所指定的。
示例请求curl -X POST “https://data-api.x.com/insights/engagement/28hr”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“tweet_ids”: [
“123456789”
],
“engagement_types”: [
“impressions”,
“engagements”
],
“groupings”: {
“hourly-time-series”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]
}
}
}‘
响应示例{
“start”: “2015-09-14T17:00:00Z”,
“end”: “2015-09-15T22:00:00Z”,
“hourly-time-series”: {
“123456789”: {
“impressions”: {
“2015-09-14”: {
“17”: “551”,
“18”: “412”,
“19”: “371”,
“20”: “280”,
“21”: “100”,
“22”: “19”,
“23”: “6”
},
“2015-09-15”: {
“00”: “5”,
“01”: “2”,
“02”: “7”,
“03”: “3”,
“04”: “1”,
“05”: “0”,
“06”: “0”,
“07”: “0”,
“08”: “0”,
“09”: “0”,
“10”: “0”,
“11”: “0”,
“12”: “0”,
“13”: “0”,
“14”: “0”,
“15”: “0”,
“16”: “0”,
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”
}
},
“engagements”: {
“2015-09-14”: {
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”,
“22”: “0”,
“23”: “0”
},
“2015-09-15”: {
“00”: “0”,
“01”: “0”,
“02”: “0”,
“03”: “0”,
“04”: “0”,
“05”: “0”,
“06”: “0”,
“07”: “0”,
“08”: “0”,
“09”: “0”,
“10”: “0”,
“11”: “0”,
“12”: “0”,
“13”: “0”,
“14”: “0”,
“15”: “0”,
“16”: “0”,
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”
}
}
}
}
}
不可用的 Tweet ID对于包含已不可用 Tweet ID（例如已被删除）的查询，系统将为所有可用的 Tweet ID 返回相应数据，不可用的 Tweet ID 将在名为 unavailable_tweet_ids 的数组中列出。例如：

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
POST /insights/engagement/historical

此历史 endpoint 支持在任意最长 4 周的时间范围内，检索最多 25 条 Tweets 的曝光与互动数据。目前，API 不支持请求早于 2014 年 9 月 1 日的数据。该历史 endpoint 还支持对所有受支持的各项度量进行查询。有关受支持度量的完整列表，请参阅度量可用性。
请求方法HTTP POST
URLhttps://data-api.x.com/insights/engagement/historical
内容类型application/json
压缩Gzip。要使用 Gzip 压缩发送请求，请在连接请求中发送 Accept-Encoding 标头。
标头应如下所示：

Accept-Encoding: gzip
POST 格式请求可以作为 POST 请求发送，其中请求体是包含 Tweet ID 集合和所需分组的 JSON 对象。POST 格式为包含 tweets、engagements 和 groupings 对象的数组。每个请求最多可包含 25 个 Tweet ID。每个请求可以指定自定义的开始和结束日期，持续时间最长为四周。


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
开始和结束日期可以使用 start 和 end 值作为请求的一部分来指定自定义的开始和结束日期。您必须指定持续时间不超过 4 周的开始和结束日期。目前最早的开始日期是 2014 年 9 月 1 日。不支持未来的结束日期。如果未提供开始和结束日期，API 将默认为紧接着的前 4 周。

Engagement API 可以返回数据的最低粒度是按小时。对于使用不直接落在小时边界上的开始或结束值发出的任何请求，请求将默认为最近的包含小时。例如，使用 “start”:“2015-07-01T12:24:00Z” 和 “end”:“2015-07-10T08:37:00Z” 的请求将默认为 “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z”。
Tweet ID包含要查询参与度数据的 Tweet ID 的数组。请注意，您只能请求由认证 @handle 创建的 Tweet 的数据。4 周历史 endpoint 每个请求最多支持 25 个 Tweet，且 Tweet ID 必须表示为字符串。
参与度类型包含要查询的参与度度量类型的数组。

对于 4 周历史 endpoint，支持 impressions、engagements 和所有单独的参与度类型作为度量。有关支持的参与度度量的完整列表，请参阅参与度数据。

**注意：**目前有三个度量对于 2015 年 9 月 15 日之前的查询将显示为零：favorites、replies 和 retweets。
分组Engagement API 的结果可以以不同的组返回，以最好地满足您的需求。每个请求最多可以包含 3 个分组。

对于每个分组，您可以定义一个自定义分组名称，以便在您的应用程序中更容易引用此分组类型。定义分组名称后，您可以选择按以下一个或多个值进行分组：
tweet.id
engagement.type
engagement.day
engagement.hour
分组按顺序执行，因此您可以通过更改 group_by 值的顺序来更改所需的结果格式。一个按 Tweet ID、度量类型分离度量的示例分组如下所示：

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


具有 4 个 group_by 项的分组仅在使用以下两个顺序之一时有效。在单个分组中具有 4 个 group_by 项但不是以下之一的请求将返回错误。此外，每个请求只允许一个具有 4 个 group_by 项的分组。

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
POST 大小限制一次最多可以为 25 个 Tweet ID 发出请求。
响应格式JSON。您的请求标头应为响应指定 JSON 格式。
请求速率限制您将按分钟进行请求速率限制，具体限制根据您的访问级别在合同中指定。
示例请求curl -XPOST “https://data-api.x.com/insights/engagement/historical”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“start”: “2015-08-01”,
“end”: “2015-08-15”,
“tweet_ids”: [
“123456789”,
“223456789”,
“323456789”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“types-by-tweet-id”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}‘
响应示例{
“start”: “2015-08-01T00:00:00Z”,
“end”: “2015-08-15T00:00:00Z”,
“types-by-tweet-id”: {
“123456789”: {
“impressions”: “0”,
“engagements”: “0”,
“url_clicks”: “0”,
“detail_expands”: “0”
},
“223456789”: {
“impressions”: “788”,
“engagements”: “134”,
“url_clicks”: “30”,
“detail_expands”: “1323”
},
“323456789”: {
“impressions”: “4”,
“engagements”: “0”,
“url_clicks”: “2”,
“detail_expands”: “0”
}
}
}
不可用的 Tweet ID对于包含已不可用 Tweet ID（例如已被删除）的查询，系统将为所有可用的 Tweet ID 返回相应数据，不可用的 Tweet ID 将在名为 unavailable_tweet_ids 的数组中列出。例如：

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:27:50Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
响应代码

StatusTextDescription
200OK请求成功。
400Bad Request通常因请求中包含无效的 JSON，或未发送任何 JSON 负载而返回此响应。
401Unauthorized由于凭据无效，HTTP 身份验证失败。请检查你的 OAuth 密钥和令牌。
404Not Found在请求发送到的 URL 未找到资源，可能因使用了错误的 URL。
429Too Many Requests你的 App 已超出 API 请求配额。
500Internal Server ErrorGnip 端发生错误。请使用指数退避策略重试请求。
502Proxy ErrorGnip 端发生错误。请使用指数退避策略重试请求。
503Service UnavailableGnip 端发生错误。请使用指数退避策略重试请求。

​
错误消息

在不同场景下，Engagement API 会返回与情境相关的错误消息，您的应用应能够妥善处理。下表列出了这些错误消息的常见示例以及解读方式。请注意，在许多情况下，Engagement API 会在 200 OK 响应中针对可用的 data 返回部分结果，并附带特定错误消息以提供更多信息。
Error MessageDescription
"errors":["Your account could not be authenticated. Reason: Access token not found"]请求的身份验证部分出现错误。“Reason”应提供有助于排查的问题线索。若您无法自行解决，请将包含“Reason”在内的完整错误发送给我们的支持团队。
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]您请求的 Tweet ID（单个或多个）已不可用，通常表示它们已被删除，或因其他原因不再对公众可见。
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]您在 /totals endpoint 上请求的 Tweet ID（单个或多个）不在 90 天以内，因此无法返回 impressions 或 engagements 度量。
"errors":["Forbidden to access tweets: *TWEET_IDS*"]基于您用于代表第三方检索数据的身份验证令牌，您请求的 Tweet ID（单个或多个）不可访问。
⌘I