跳转到主要内容

​
概览

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

​
请求端点

Engagement API 提供三个请求端点：

​
当前总览：[/totals]

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

​
过去 28 小时：[/28hr]

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

​
历史：[/historical]

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

​
可用指标

下表说明可通过 Engagement API 获取的指标类型。 请参阅我们的指标解读页面，了解上述指标的更多信息。
度量端点可用性需要用户上下文信息描述
展示量全部是的该 Post 的浏览次数统计。此指标仅适用于过去 90 天内发布的 Post。
互动量所有是统计用户与该 Post 的互动次数。此指标仅适用于过去 90 天内发布的 Post。
收藏全部是 - /28小时&/历史记录

否 - /totals		该 Post 被收藏的次数计数。
转推所有是 - /28小时&/历史记录

否 - /totals		统计该 Post 被转发（Retweet）的次数。
引述_Tweets/totals否 - /totals对带评论的转发（亦称 Quote）的 Post 次数统计。
回复所有是 - /28小时&/历史

否 - /totals		该 Post 的回复次数统计。
视频_展示次数全部是 - /28小时&/历史

否 - /totals		统计给定 Post 中视频在至少两秒内达到 50% 可见的次数。

视频观看次数仅适用于不超过 1800 天的 Post。若你尝试请求超过 1800 天的 Post 的视频观看次数，响应中将包含以下对象，此外还会另附一个包含你所请求其他指标的单独对象：

“不受支持_用于_视频_浏览量_Tweet_ids”: [“Tweet_ID”]

**请注意：**您可能会发现，X 自有与运营的平台（移动应用与网站）上显示的“视频观看次数”指标，可能与您通过 /28hr 和 /historical 端点获取的数值不一致。

- X 用户界面中显示的，以及通过 /totals 端点返回的视频观看次数，是将该视频在所有包含该视频的 Posts 中的观看次数进行汇总后展示的。这意味着 UI 中显示的指标包含该视频在被 Retweet 或以单独 Posts 形式被转发/转载时产生的所有观看次数的总和。该指标不包含 gif 的视频观看次数。
- /28hr 和 /historical 端点提供的视频观看次数仅包含你正在拉取指标的那个特定 Post 自身产生的观看次数。该指标不包括 GIF 的视频观看次数。
媒体_展现次数/28小时 /historical是的您媒体在视频、GIF 和图片中的所有浏览（自动播放与点击）的总次数。
媒体_互动量

(原名 Media Clicks)		/28hr /historical是对 Post 中媒体（如图片或视频）被点击次数的统计。
url_点击量/28hr /historical是对 Post 中 URL 被点击次数的计数。
话题标签_点击量/28小时 /历史是的统计该 Post 中某个话题标签被点击的次数。
详细_扩展/28小时 /historical是的显示用户为查看更多详细信息而点击该 Post 的次数。
固定链接_点击量/28小时 /historical是该 Post 的永久链接（指向此 Post 的独立网页）被点击的次数。
应用_安装_尝试次数/28 小时 /historical是的从该 Post 产生的 App 安装事件次数统计
应用_打开量/28小时 /历史数据是从该 Post 产生的 App Open 事件的发生次数统计。
电子邮箱_Tweet/28hr /historical是该 Post 通过电子邮件被分享的次数。
用户_关注者/28hr /historical是从此 Post 触发对该用户（Post 作者）发起关注的次数统计。
用户_个人资料_点击量/28hr /historical是的统计从此 Post 点击进入该用户（Post 作者）个人资料的次数。

​
互动分组

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

​
使用指南

​
开发者快速入门指南

​
简介

本文档旨在为开发者介绍如何集成 Engagement API。我们将先讨论为何要进行集成，随后再深入探讨技术层面的实现细节。
Engagement API 提供什么功能？
  • Engagement API 可为任何 X 账号在过去 90 天内发布的自有 Posts 提供展示与互动数据，前提是该账号已授权你的应用使用 三方 OAuth 代表其请求相关指标。这个功能强大且易于集成的解决方案，可立即获取展示量以及更深层的互动数据，如 URL 点击、#hashtag 点击等。
  • Engagement API 为任何 Post 提供点赞、转发（Retweets）、引用转发（Quote Tweets）、回复和视频观看次数等的汇总总量指标。这可作为获取任意单条或多条 Posts 基础互动数据的有力方式。
  • Engagement API 通过提供 15+ 项性能指标，帮助客户有效衡量内容表现，从而为社媒聆听、营销和发布平台创造新价值，并量化在 X 上的投资回报（ROI）。
  • Engagement API 是一种请求/响应式 API，允许应用开发者发送包含 Post id、所需指标和时间范围的请求，API 会即时返回数据。  
为何集成？示例用例
  • 了解你内容的整体覆盖，看看有多少人看到。查看有多少人观看视频、点击链接、点击话题标签，或安装我的应用。
  • 生成总体与时间序列的互动指标。
  • 了解任意公开 Post 的基础互动指标（点赞、Retweet、Quote Tweets、回复）。
  • 利用这些指标判断哪些类型的 Posts 表现更好，从而更高频地发布此类内容，为我的内容获得更多曝光和互动。
  • 自动化营销行为（例如，当我的某条 Post 达到 100 次点赞或其他阈值时，从另一个自有账号 Retweet 该内容）。
  • 将我的活动相互对标与比较，用于 A/B 测试。
  • 分析哪些类型的内容能与我的客服团队的目标产生共鸣，以决定如何以及何时回应。
  • 展示在我的平台发布的内容的分析数据。  
Engagement API 于 2016 年发布，是首个在大规模提供深度互动指标的 X API。Engagement API 易于使用，并支持客户实现流程自动化。以下是一份描述示例集成的案例研究： 既然我们已经讨论了 Engagement API 的“为什么”，接下来开始深入技术细节。

​
集成 Engagement API

API 简介
Engagement API 是一个简单的 RESTful API，它接收以 JSON 编码的请求，并返回以 JSON 编码的互动度指标。请求由三个主要部分组成（可通过以下链接获取更多文档）：
  • Post ID 数组。
  • 指定所需指标类型的数组。类型包括 “impressions”、“retweets”、“hashtag_clicks” 和 “user_follows” 等。
  • 互动分组，这是一个 JSON 结构，用于指示你希望在 API 响应中如何组织互动数据。
在很多情况下，Engagement 类型和分组在各次请求之间相对保持不变，只有 Post ID 会更新。 Engagement API 提供了三个端点：
  • Totals - 提供 Posts 的互动总数。部分指标适用于所有 Posts，而另一些仅适用于过去 90 天。
  • 28 hour - 提供过去 28 小时的时间序列互动指标。
  • Historical - 为自 2014 年 9 月 1 日以来发布的 Posts 提供最长连续四周的时间序列互动指标。
/totals 端点支持在一次请求中为最多 250 个 Posts 请求指标。/28hour 和 /historical 端点支持 每次请求 25 个。 在讨论如何获取 Engagement API 的访问权限后，我们将演示如何发起 API 请求，提供 OAuth 概览，并附上其他技术资源的链接。
获取 API 访问权限
如果你正在阅读此文档，你很可能已经获得了 Engagement API 的访问权限。若尚未获得，请联系你的 Enterprise 客户经理，或在此处申请 Enterprise 访问。 第一步是通过开发者门户，使用已获批准的开发者账户创建一个X 应用。你的客户经理需要此应用关联的数值型 App ID 以便为你开通访问。如果你需要申请开发者账户，可在此处进行申请。
发起请求
好消息是，向 Engagement API 发起请求非常简单。此次我们将查询以下两条 @XDevelopers Post 的转发（Retweets）、引用 Tweet（Quote Tweets）、收藏（Favorites）和回复的总数：
1/ 今天我们分享对 X API 平台未来的愿景！https://t.co/XweGngmxlP https://t.co/XweGngmxlP — Twitter Dev (@TwitterDev) 2017 年 4 月 6 日
不要错过那些讨论你 Post 的 Posts。 pic.x.com/oanjZfzC6y 现在在 iOS 上，你可以在同一位置查看带评论的转发。pic.x.com/oanjZfzC6y — X (@X) 2020 年 5 月 12 日
第一步是用 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"
      ]
    }
  }
}
要检索这些汇总指标，我们向 https://data-api.x.com/insights/engagement/totals 端点发送一条 JSON 格式的 POST 请求。 我们将包含以下请求头，用于指明请求使用 JSON 编码，并启用了 Gzip 压缩（请求正文可能会较大）：
  • Content-Type: application/json
  • Accept-Encoding: gzip  
发起请求时我们使用 OAuth 进行身份验证，相关内容将在下一节进一步说明。 API 将返回以下有效负载： 
{
  "分组名称": {
    "1260294888811347969": {
      "喜欢": "17111",
      "引用推文": "3254",
      "回复": "1828",
      "转推": "5218"
    },
    "850006245121695744": {
      "喜欢": "492",
      "引用推文": "66",
      "回复": "42",
      "转推": "324"
    }
  }
}
请注意，响应中的指标按照“groupings”定义所描述的结构组织：首先按 Post ID 列出，其次在下一层级按互动类型分组。 这很简单。如果你是首次使用 OAuth 进行身份验证，请查看下一节。

​
使用 OAuth 进行认证

OAuth 是技术行业中非常常见的认证标准。如果你已经在使用 OAuth（例如与其他 X API 一起使用），通常会借助某种特定语言的 OAuth 包来屏蔽繁琐细节。如果你是首次接触 OAuth，请访问我们的使用 X API 的 OAuth页面，或直接前往 https://oauth.net 了解更多。接着，我们建议你为所使用的集成语言选择合适的 OAuth 包并从其入手。使用这些包，完成认证的典型流程通常包括：配置密钥和令牌，创建某种 HTTP 对象，然后使用该对象发起请求。 例如，在 Ruby 生态中，下面的伪代码演示了使用 Ruby gem “oauth” 构建支持 OAuth 的应用并发起 POST 请求的示例方案： 
require 'oauth'

#组装 JSON 请求(如上所示)。
request = make_json_request()

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

#创建启用 OAuth 的应用对象。
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 端点为未持有的公开 Post 收集互动指标，则无需用户授权，你可以使用仅应用认证。在这种情况下，你只需使用你的应用密钥和密钥（secret）进行认证。 OAuth 也允许应用使用与用户关联的令牌“代表另一位用户”发起 API 请求。若你为已持有的 Post 生成 Engagement 指标，即由你拥有其用户令牌的用户发布的 Post，你将以用户上下文发起请求，这意味着需要同时使用你的应用密钥和用户特定的访问令牌进行认证。这些用户访问令牌通常通过‘Sign-in with X’流程提供，或直接由用户提供（请注意，若你直接从用户处获取令牌，必须使用 twurl）。一旦用户提供了其令牌，这些令牌不会过期，并且只要用户不重置令牌或更改密码，就可以与 Engagement API 一起使用以代表其发起请求；若发生上述情况，用户需要向你提供新的令牌。 你可以通过 此表 查看各指标所需的认证方式。

​
选择 Engagement API 端点

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

​
关键概念

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

​
端点与示例用例

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

​
Engagement API 关键特性

  • RESTful API 提供 JSON 数据，支持带有 JSON 请求体的 POST 请求。
  • 请求类型： 客户端应用可发起以下类型的请求：
    • 总互动量 — 向 /totals 端点发起 HTTP POST 请求
    • 过去 28 小时互动量 — 向 /28hr 端点发起 HTTP POST 请求
    • 历史互动量 — 向 /historical 端点发起 HTTP POST 请求
  • OAuth 认证：
    • OAuth 1.0 用户上下文：当某位用户通过 三方（3-legged）OAuth 授权你的应用后，该用户所拥有的 Posts 的所有可用指标均可获取。发起请求时必须使用该用户的访问令牌（Access Tokens）。
    • OAuth 2.0 Bearer Token：部分指标（转发 Retweets、引用推文 Quote Tweets、回复 Replies、收藏 Favorites 和视频观看 Video Views）适用于任何公开的 Post。 
  • 请求元数据与结构：请求体为一个 JSON 对象，由 Post ID 数组、互动类型数组以及互动分组结构组成。
  • 每次请求的 Posts 数量：
    • /totals 端点：250 个 Post ID
    • /28hr 端点：25 个 Post ID
    • /historical 端点：25 个 Post ID
  • 互动指标可用性：
    • /totals — 自 Post 发布起的累计指标。Impressions 和 Engagements 适用于过去 90 天内发布的 Posts，而 Retweets、Quote Tweets、Replies、Favorites 和 Video Views 适用于所有 Posts。
    • /28hr — 自请求时间起的最近 28 小时。
    • /historical — 自 2014 年 9 月 1 日起任意连续 28 天的区间。
  • 指标类型：每个请求包含一个 Metric Types 数组。其可用性取决于端点；如果请求 /totals 端点，还取决于 Posts 是否获得用户授权。
    • /totals 端点：
      • 所有 Posts：Favorites、Retweets、Quote Tweets、Replies 和 Video Views
      • 需要 OAuth 1.0a 用户上下文：Impressions、Engagements、Favorites、Replies 和 Retweets
    • /28hr 和 /historical 端点（需要使用 Post 所有者访问令牌的 OAuth 1.0a 用户上下文）：Impressions、Engagements、Favorites、Replies、Retweets、URL Clicks、Hashtag Clicks、Detail Click、Permalink Clicks、Media Clicks、App Install Attempts、App Opens、Post Emails、Video Views 和 Media Views
  • 互动分组： 每个请求包含一个 Engagement Groupings 数组。通过这些分组，你可以自定义返回指标的组织方式。每个请求最多可包含三个分组。指标可按以下维度组织：
    • 所有端点：Post ID、Engagement Type
    • /28hr 和 /historical 端点：如指定以下额外分组，将提供时间序列：Engagement Day、Engagement Hour
  • 集成要求： 你的团队将负责以下事项。
    • 创建并维护一个客户端应用，能够向 Engagement API 发送 HTTP 请求，并返回请求中包含的 Post ID 的互动指标。
  • 限制
  • 仅对发布时间不超过 1800 天的 Posts 提供视频观看次数。

​
使用 Engagement API 进行认证

请注意： 在你开始使用该 API 之前，X 需要为你的开发者应用启用对 Engagement API 的访问。为此，请务必将你计划用于认证的应用 ID 提供给你的客户经理或技术支持团队。
Engagement API 提供两种认证方式：OAuth 1.0a 和 OAuth 2.0 Bearer Token。 OAuth 2.0 Bearer Token（也称“application-only”）允许访问公开可用的互动指标。在向 /totals endpoint 发起请求时，可用于获取任何公开可见的 Post 的 Favorites（即 Likes）、Retweets、Quote Tweets、Replies，以及视频观看次数的总量。 OAuth 1.0a（也称“user context”）允许你代表某位用户发起请求，并访问该用户的私有互动指标。 此认证方式在以下情况下必需：
  • 发送到 /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 Token 及其 Secret）。如果在请求受保护的用户数据时未提供正确的用户访问令牌，Engagement API 将返回 403 Forbidden 错误。 即使你代表这些 Post 的所有者进行认证，Engagement API 也不允许你获取受保护的 Posts 的互动数据。尝试这样做将返回 400 Bad Request 错误，错误信息为 "Tweet ID(s) are unavailable"。 如果你代表自己的 X 账号（即拥有该开发者应用的账号）发送请求，你可以直接在开发者门户中该开发者应用的“Keys and tokens”选项卡下生成所需的访问令牌。 如果你代表其他用户发送请求，你需要使用三方（3-legged）OAuth 流程来获取所需的访问令牌。更多信息请参阅以下文档：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 的更新，以增强全平台指标的一致性。  我们近期对 Engagement API 进行了现代化改造，使其采用与 X 分析仪表板（analytics.x.com）一致的指标聚合方法。在推出这些新指标时，我们尽量减少破坏性 API 变更，并于 2017 年 10 月 9 日部署了第一批更新。这些变更提升了你或你的客户在各处监控 X 表现时的一致性。请参阅下方详细变更说明：
指标变更
engagements我们更新了计入总体 engagements 的子指标，使其与 Post 分析仪表板保持一致。Engagements 衡量“用户与该 Post 互动的次数”。

对于包含视频或 GIF 等媒体的 Posts，engagements 指标将不再包含媒体观看数。媒体观看数现可通过新指标 media_views 获取。
media_clicks*此指标已由名为“media_engagements”的新指标取代。
video_views自 2018 年 7 月 6 日起，此指标可通过 /totals 端点用于“非自有”Posts。这意味着你可通过仅使用应用级认证访问获取所有 Posts 的视频观看数。 

你只能请求距今不超过 1800 天的视频观看数。若尝试请求超过 1800 天的 Post 的视频观看数，你将收到以下内容：

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

请注意，该指标与 media_views 不同，video_views 依据 MRC 标准：至少有 50% 的视频在视窗内持续两秒。

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

 X 用户界面中显示并通过 /totals 端点提供的视频观看数，将聚合某个视频在其被发布到的所有 Posts 中产生的观看总数。也就是说，UI 中的指标包含该视频在被转发（Retweet）或在不同 Posts 中重新发布时的合并观看数。
 /28hr 与 /historical 端点提供的视频观看数，仅包含你为之拉取指标的特定 Post 所产生的观看数。
media_views包含你媒体（视频、vines、gifs 与图片）的所有观看（自动播放与点击）。

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

​
解读指标

注意： 你可能会发现部分 X 网页控制台上报告的 data 与 Engagement API 报告的 data 存在差异。造成这种差异的原因在于，网页控制台通常只展示选定时间范围内发生的互动和/或曝光。例如，某个网页控制台可能只展示某个日历月内对 Post 的互动，而 Engagement API 可能会展示超出该月范围、但仍在所请求时间范围内的互动。在上述情况下，应以 Engagement API 为权威数据来源。  

​
展示量与互动数据

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

​
视频指标

在 X 中，有多种用于表示媒体曝光的指标。第一种是我们的视频观看量指标，遵循 MRC 标准：至少有 50% 的视频画面在可视区域内且持续至少两秒。第二种是 Media Views（媒体观看），它统计跨视频、Vine、GIF 和图片的所有观看（自动播放与点击）。 视频观看量指标适用于自有 Posts，可通过 /28hour 和 /historical 端点获取；对于所有非自有 Posts，可通过 /totals 端点获取。  尽管 X 用户界面中的视频观看量同样采用 MRC 标准，但请注意：X 自有及运营的平台（移动应用和网站）上显示的视频观看量，可能与您通过不同 Engagement API 端点获得的数值存在差异。
  • /totals 端点和 X 用户界面提供的视频观看量，会显示某个视频在所有包含该视频的 Posts 中的汇总观看量。这意味着，通过 /totals 提供并在 X UI 中显示的指标，包含该视频在被 Retweet 或在其他 Post 中转发时的合并观看量。
  • /28hour 和 /historical Engagement API 端点提供的视频观看量，仅包含由您拉取指标的特定 Post 所产生的观看量。   
请注意，我们不提供超过 1800 天之前的 Posts 的视频观看量。取而代之的是，我们会返回一个对象，列出超过 1800 天的 Posts。对于您请求的 Posts，其他所有指标仍会在单独的对象中返回。以下是一个示例响应： 
{
  "不支持视频观看次数的推文ID": [
    "479311209565413376",
    "477139122520219648"
  ],
  "分组名称": {
    "479311209565413376": {
      "收藏": "69",
      "展示次数": "1692",
      "转发": "142",
      "视频观看次数": "0"
    },
    "477139122520219648": {
      "收藏": "10",
      "展示次数": "1023",
      "转发": "6",
      "视频观看次数": "0"
    },
    "1397568983931392004": {
      "收藏": "268",
      "展示次数": "26803",
      "转发": "56",
      "视频观看次数": "17902"
    }
  }
}
“Media Views” 指标仅适用于自有的 Post，且仅在 /28hour 与 /historical 端点可用。

​
Engagement API 分组

分组可用于自定义组织返回的互动指标。每个请求最多可包含 3 个分组。你可以按以下一个或多个值对指标进行分组： 以下三个端点均支持：
  • 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": [
    "点赞",
    "回复",
    "转推"
  ],
  "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"
        }
      }
    }
  }
}

​
常见问题

企业版

​
Engagement API

通过企业版订阅可获得对 Engagement API 的访问权限。请填写此表单以联系销售团队。
如果你的合同对可与 Engagement API 搭配使用的唯一 handle 数量设有限制，X 的内部系统将跟踪使用 Engagement API 查询到的、其所发 Post 被检索的已认证用户数量。客户也应在客户端自行记录这一唯一数量。目前没有用于查看 Engagement API 的 @handle 使用情况的用量 API 或 UI。如果请求的 @handle 数量超过合同约定，系统不会拦截超量。在结算月结束时，查询到的唯一 @handle 数量将与合同约定的数量进行比对，并按合同条款收取超额费用。
目前没有用于查看 Engagement API 的 @handle 使用情况的用量 API 或 UI。如果请求的 @handle 数量超过合同约定，系统不会拦截超量。在结算月结束时，查询到的唯一 @handle 数量将与合同约定的数量进行比对，并按合同条款收取超额费用。返回负载中的 engagements 元数据字段不等于各类互动指标总和。为什么会这样？这是预期行为。engagements 元数据字段可能并不总是与 API 返回的各项互动指标之和相匹配，因为它可能包含在负载中未单独拆分为具体指标的其他互动。换句话说，把各种互动指标的总数相加，可能与负载中 engagements 指标字段的数值不一致。你可以将 engagements 元数据字段理解为对该 Post 的任何点击或交互。  当 Post 实际没有 URL 时，负载响应中的 url_clicks 字段却返回了一个数值。这怎么可能？这可能是因为包含某些内容（例如会生成到其他页面链接的标签）的 Post，被用户点击后也会计为一次 URL 点击。  
你可能无法检索某个特定 Post 的互动数据，原因包括：
  • 你请求的 Post ID（或多个 ID）在你代表第三方检索数据所使用的认证令牌下不可用。
  • 你为 /totals 端点请求的 Post ID（或多个 ID）早于 90 天，因此无法返回展示或互动指标。
  • 你请求的 Post ID（或多个 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 端点进行认证时，请确保不要使用任何 access token 或 secret。原因是，如果你包含了这些令牌且尝试拉取与这些令牌无关联的 Post 的内容，很可能会收到如下错误：
[
    Forbidden to access tweets: 1054424731825229824;
]

​
仍然找不到您需要的内容？

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

​
API 参考文档

​
POST insights/engagement

​
方法

方法说明
POST /insights/engagement/totals获取一组 Tweet 的总曝光量和互动量。
POST /insights/engagement/historical获取一组 Tweet 在最长 4 周的时间范围内（可回溯至 2014 年 9 月 1 日）的曝光量和互动量。
POST /insights/engagement/28hr获取过去 28 小时内一组 Tweet 的曝光量和互动量。

​
认证

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

​
POST /insights/engagement/totals

该 totals 端点可一次性为最多 250 条 Tweet 获取当前的总曝光量和互动量。
请求方式HTTP POST
URL（链接）https://data-api.x.com/insights/engagement/totals
内容类型application/json
压缩Gzip。要使用 Gzip 压缩发起请求，请在连接请求中包含 Accept-Encoding 标头。
标题应如下所示：

Accept-Encoding: gzip
Post 格式请求可以作为 POST 请求发送，请求体为一个 JSON 对象，包含一组 Tweet ID 和所需的分组方式。该 POST 的格式为一个数组，包含tweets，互动，和groupings对象。每个请求最多可包含 250 个 Tweet id。

示例 POST 请求体如下：


{
“Tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”，
“Tweet ID 3”
],
“互动_类型”: [
“曝光量”，
“互动量”，
“收藏”，
“引述_推文”
],
“分组”：{
“分组名”：{
“组_作者：”: [
“tweet.id”，
“engagement.type”
]
}
}
}
Tweet IDs一个数组，包含需查询互动数据的 Tweet ID。请注意，您只能请求由进行身份验证的 @handle 创建的 Tweets 的数据。每个请求最多可包含 250 条 Tweet，且 Tweet ID 必须以字符串表示。
互动类型一个数组，includes 要查询的互动指标类型。Totals 端点仅支持以下互动类型：展示次数，互动，favorites,转发数，quote_tweets，回复，video_views。
The/totals该端点支持检索功能展示和互动针对在过去 90 天内创建的 Tweet，且favorites，转发，quote_tweets，replies，及video_views适用于任意 Tweet。
分组Engagement API 的结果可按不同分组返回，以更好地满足您的需求。每个请求最多可包含 3 个分组。

对于每个分组，您可以自定义一个分组名称，便于在应用中引用该分组类型。

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

分组会按序依次生效，因此你可以通过调整分组的顺序来改变所需的结果格式_按 values。如下示例分组会将指标按 Tweet ID 与指标类型分别展示：


“分组”:{
“我的分组名称”:{
“组_由”: [
“Tweet.id”，
“engagement.type”
]
}
}
POST 尺寸限制每个请求最多可包含 250 个 Tweet ID。
响应格式JSON。您的请求头应指定响应采用 JSON 格式。
请求速率限制系统将按分钟对你进行速率限制，具体额度依据你的访问级别，以合同约定为准。
示例请求（公共指标）curl —request POST
—urlhttps://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”
],
“互动_类型”: [
“收藏夹”，“转推”，“回复”，“引文_Tweets”，“视频_浏览量”
],
“分组”:{
“perTweetMetricsUnowned”：{
“组_作者”: [
“Tweet.id”，
“engagement.type”
]
}
}
}
—verbose
—compressed
示例请求curl —request POST
—urlhttps://data-api.x.com/insights/engagement/totals
—header’accept-encoding: gzip’
—header’authorization: OAuth 授权_使用方_key=“应用的 consumer key”,oauth_nonce=“生成的随机数（nonce）“,oauth_signature=“已生成的签名”,oauth_签名_method=“HMAC-SHA1”，OAuth_timestamp=“生成时间戳”,oauth_token=“已授权用户的访问令牌”, OAuth_version=“1.0”’
—header’content-type: application/json’
—data’{
“Tweet_ids”: [
“1060976163948904448”，“1045709644067471360”
],
“互动_类型”: [
“收藏”，“回复”，“转推”，“视频_浏览量”，“曝光量”，“互动量”
],
“分组”:{
“perTweetMetricsOwned”:{
“组_作者：”: [
“tweet.id”，
“engagement.type”
]
}
}
}’
—verbose
—compressed
示例响应（公开度量）{
“每条Tweet指标（非所属）”:{
“1021817816134156288”:{
“收藏”:“530”，
“引述_Tweet”:“79”，
“回复”:“147”，
“转推数”:“323”，
“视频_展示次数”：“0”
}，
“1067094924124872705”：{
“收藏”:“1360”，
“引述_推文”:“29”，
“回复”:“56”，
“转推”：“178”，
“视频_浏览量”：“5754512”
}，
“1070059276213702656”：{
“收藏”：“69”,
“引述_Tweet”：“5”，
“回复”:“7”，
“转推”:“26”，
“视频_浏览量”：“0”
}
}
}
示例回复{
“perTweetMetricsOwned”：{
“1045709644067471360”：{
“互动量”：“2”,
“收藏”：“0”,
“展示量”:“47”，
“回复”：“0”，
“转推”：“8”，
“引述_Tweets”：“5”，
“视频_查看量”：“0”
}，
“1060976163948904448”:{
“互动量”：“4”,
“收藏”：“0”，
“曝光量”：“148”，
“回复”：“1”，
“转推”：“9”，
“引述_Tweet”：“2”，
“视频_浏览量”：“0”
}
}
}
不可用的 Tweet id对于包含已不可用的 Tweet ID（例如已删除）的查询，系统会为所有可用的 Tweet ID 返回相应的 data，而不可用的 Tweet ID 将会在名为unavailable_tweet_ids。例如：

{
“开始”：“2015-11-17T22:00:00Z”，
“结束”：“2015-11-19T02:00:00Z”，
“不可用_Tweet_ids”: [
“323456789”
],
“group1”：{
“423456789”：{
“收藏”：“67”，
“回复”：“8”，
“转推数”：“26”，
“引文_Tweet”:“2”
}
}
}

​
POST /insights/engagement/28hr

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

Accept-Encoding: gzip
Post 格式可以将请求以 POST 方式发送，其中请求体为一个 JSON 对象，包含一组 Tweet ID 以及期望的分组方式。POST 的格式为一个数组，包含tweets，互动，以及groupingsobject。每个请求最多可包含 25 个 Tweet ID。

示例 POST 请求的请求体如下：


{
“Tweet_ids”: [
“Tweet id 1”，
“Tweet ID 2”，
“Tweet id 3”
],
“互动度_类型”: [
“展示量”，
“互动量”，
“URL_点击量”，
“详情_扩展”
],
“分组”：{
“分组名称”：{
“组_作者”: [
“tweet.id”，
“engagement.type”，
“参与.小时”
]
}
}
}
Tweet ID（复数）一个数组，包含要查询互动数据的 Tweet 的 Tweet ID。请注意，您只能请求由进行身份验证的 @handle 创建的 Tweet 的数据。28 小时的端点每次请求最多支持 25 条 Tweet，且 Tweet ID 必须以字符串形式表示。
互动类型要查询的互动指标类型数组。

对于 28 小时的端点，展示次数，互动，以及所有单独的互动类型均为受支持的指标。有关受支持的互动指标的完整列表，请参见互动指标。
分组Engagement API 的结果可按不同分组返回，以更好地满足你的需求。每个请求最多可包含 3 个分组。

对于每个分组，您可以自定义分组名称，便于在您的应用中引用此分组类型。定义分组名称后，您可以选择按以下一个或多个值进行分组：
tweet.id
engagement.type
engagement.day
engagement.hour
分组按顺序生效，因此你可以通过调整分组顺序来更改期望的结果格式_按值。以下是一个示例分组，显示按 Tweet ID、指标类型分隔的各项指标，如下所示：

“分组”：{
“我的分组名”：{
“组_作者”: [
“tweet.id”，
“engagement.type”，
“engagement.day”
]
}
}


包含 4 个的分组group_by仅当按以下两种顺序之一排列时，items 才有效。包含 4group_by在单个分组中，凡不属于下列任一项的条目都会导致错误。此外，仅允许存在一个包含 4 个 group_by 条目的分组。group_by每个请求允许的项目数量上限为 items。

“群组_由”: [
“tweet.id”，
“engagement.type”，
“engagement.day”，
“engagement.hour”
]

“组_由”: [
“engagement.type”，
“tweet.id”，
“engagement.day”,
“参与度.小时”
]
POST 请求大小限制每次请求最多可包含 25 个 Tweet ID。
响应格式JSON。您的请求头应指定响应的 JSON 格式。
速率上限根据你的访问级别，系统将按分钟进行速率限制，具体以你的合同约定为准。
请求示例curl -X POST”https://data-api.x.com/insights/engagement/28hr”
-H’Accept-Encoding: gzip’
-H’授权 OAuth oauth_使用方_key=“应用的 consumer key”,oauth_随机值=“生成的随机数值”,oauth_signature=“生成签名”,oauth_签名_method=“HMAC-SHA1”, OAuth_timestamp=“生成时间戳”,oauth_token=“authed-用户访问令牌”，OAuth_version=“1.0”’
-d’{
“Tweet_ids”: [
“123456789”
],
“互动_类型”: [
“曝光量”，
“互动量”
],
“分组”：{
“每小时时间序列”:{
“群组_作者”: [
“tweet.id”，
“engagement.type”，
“engagement.day”，
“engagement.hour”
]
}
}
}‘
示例回复{
“开始”:“2015-09-14T17:00:00Z”，
“结束”：“2015-09-15T22:00:00Z”，
“每小时时间序列”:{
“123456789”：{
“曝光次数”：{
“2015 年 09 月 14 日”：{
“17”：“551”，
“18”：“412”，
“19”：“371”，
“20”:“280”，
“21”：“100”，
“22”：“19”，
“23”:“6”
},
“2015年9月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”
}
}，
“互动量”:{
“2015年9月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 返回相应的 data；而不可用的 Tweet ID 将在名为 unavailable_tweet_ids 的数组中列出unavailable_tweet_ids。例如：

{
“开始”：“2015-11-17T22:00:00Z”，
“结束”：“2015-11-19T02:00:00Z”，
“不可用_Tweet_id 列表”: [
“323456789”
],
“group1”：{
“423456789”：{
“收藏”：“67”，
“回复”：“8”，
“转推”：26
}
}
}

​
POST /insights/engagement/historical

历史端点可在任意最长 4 周的时间范围内，获取最多 25 条 Tweet 的展示量与互动数据。目前，API 无法请求早于 2014 年 9 月 1 日的数据。历史端点还支持请求所有受支持的单项指标。有关受支持指标的完整列表，请参见指标可用性。
请求方法HTTP POST
URLhttps://data-api.x.com/insights/engagement/historical
内容类型application/json
压缩Gzip。若要使用 Gzip 压缩发起请求，请在连接请求中发送 Accept-Encoding 头。
标题应如下所示：

Accept-Encoding: gzip
Post 格式请求可以通过 POST 请求发送，其中请求体为一个 JSON 对象，包含一组 Tweet ID 以及期望的分组方式。该 POST 的格式为一个数组，包含tweets，互动数据，和groupings对象。每个请求最多可包含 25 个 Tweet ID。每个请求都可以指定自定义的开始和结束日期，时间跨度最长为四周。


{
“Tweet_ids”: [
“Tweet id 1”，
“Tweet ID 2”，
“Tweet ID 3”
],
“互动度_类型”: [
“展示量”，
“互动量”，
“URL_点击数”，
“详细信息_扩展”
],
“分组”：{
“分组名”：{
“组_作者：”：[
“tweet.id”，
“engagement.type”，
“engagement.hour”
]
}
}
}
开始日期和结束日期可以通过 … 指定自定义的开始和结束日期start和end作为请求的一部分，您必须指定 start 和 end 值，且时间范围不得超过 4 周。目前可用的最早开始日期为 2014 年 9 月 1 日。不支持将结束日期设置为未来时间。如果未提供开始和结束日期，API 将默认采用紧接当前之前的 4 周。

Engagement API 可返回的最小粒度为按小时。对于任一 Start 或 End 值未恰好落在整点边界的请求，将默认对齐到最近的包含性整点。例如，一个请求”开始”：“2015-07-01T12:24:00Z”和”结束”：“2015-07-10T08:37:00Z”将默认为”开始”：“2015-07-01T12:00:00Z”，“结束”：“2015-07-10T09:00:00Z”。
Tweet ID一个数组，包含要查询互动数据的 Tweet 的 ID。请注意，您只能请求由进行身份验证的 @handle 所创建的 Tweet 的数据。4 周历史端点每次请求最多支持 25 条 Tweet，且 Tweet ID 必须以字符串形式表示。
互动类型一个数组，包含要查询的互动指标类型。

对于 4 周历史数据端点，展示次数，互动，并且所有单项互动类型均为受支持的指标。有关受支持的互动指标的完整列表，请参见互动指标数据。

**注意：**目前，对于在 2015 年 9 月 15 日之前发起的查询，有三项指标会显示为零：收藏，replies，和转发数。
分组方式Engagement API 的结果可按不同分组返回，以更好满足你的需求。每个请求最多可包含 3 个分组。

对于每个分组，您可以定义自定义的分组名称，便于在您的应用中引用该分组类型。定义分组名称后，您可以选择按以下一个或多个值进行分组：
tweet.id
engagement.type
engagement.day
engagement.hour
分组按顺序依次生效，因此你可以通过调整分组顺序来改变所需的结果格式_按值分组。以下示例将按 Tweet ID、指标类型等对指标进行分别展示，格式如下：

“分组”：{
“我的分组合名称”：{
“群组_作者”: [
“Tweet.id”，
“engagement.type”，
“engagement.day”
]
}
}


包含 4 个的分组group_by仅当按以下两种顺序之一排列时，items 才有效。包含 4group_by在单个分组中，凡是不符合以下任一条件的项都会返回错误。此外，仅允许存在一个包含 4 个group_by每个请求允许的项目数量。

“组_由”: [
“tweet.id”，
“engagement.type”，
“engagement.day”，
“engagement.hour”
]

“组_作者”: [
“engagement.type”，
“tweet.id”，
“engagement.day”，
“engagement.hour”
]
POST 请求大小上限每次请求最多可包含 25 个 Tweet id。
响应格式JSON。您的请求头应指定响应采用 JSON 格式。
请求速率限制根据您的访问级别，您将按合同规定受到按分钟计的限流。
示例请求curl -X POST”https://data-api.x.com/insights/engagement/historical”
-H’Accept-Encoding: gzip’
-H’授权 OAuth oauth_使用方_key=“应用的consumer key”,oauth_nonce=“生成的随机数值”,oauth_signature=“生成的签名”,OAuth_签名_method=“HMAC-SHA1”，OAuth_timestamp=“生成时间戳”,oauth_token=“已认证用户访问令牌”，OAuth_version=“1.0”’
-d’{
“开始”:“2015年8月1日”，
“结束”:“2015-08-15”，
“Tweet_ids”: [
“123456789”，
“223456789”,
“323456789”
],
“互动_类型”: [
“曝光量”，
“互动”，
“URL_点击量”，
“详细信息_展开”
],
“分组”:{
“types-by-tweet-id”:{
“组_按”: [
“tweet.id”，
“engagement.type”
]
}
}
}‘
示例回复{
“开始”：“2015-08-01T00:00:00Z”，
“结束”：“2015-08-15T00:00:00Z”，
“按Tweet id分类的类型”：{
“123456789”：{
“展示次数”：“0”，
“互动量”：“0”，
“URL_点击次数”:“0”，
“详情_扩展”：“0”
}，
“223456789”：{
“展示量”：“788”，
“互动指标”：“134”，
“URL_点击次数”：“30”，
“详情_扩展”：“1323”
}，
“323456789”：{
“曝光量”：“4”，
“参与度”：“0”,
“URL_点击量”：“2”，
“详细信息_扩展”：“0”
}
}
}
不可用的 Tweet id对于包含已不可用的 Tweet ID（例如已被删除）的查询，系统会为所有可用的 Tweet ID 返回相应的 data，而不可用的 Tweet ID 则会在名为 unavailable_tweet_ids 的数组中列出。unavailable_tweet_ids。例如：

{
“开始”：“2015-11-17T22:00:00Z”，
“结束”:“2015-11-19T02:27:50Z”，
“无法使用_Tweet_ids”: [
“323456789”
],
“group1”:{
“423456789”：{
“收藏”：“67”，
“回复”：“8”，
“转推数”：26
}
}
}

​
响应代码

状态文本说明
200OK请求成功。
400Bad Request通常是由于请求中包含无效的 JSON，或未发送任何 JSON 负载所致。
401Unauthorized由于凭据无效导致 HTTP 认证失败。请检查你的 OAuth 密钥和令牌。
404Not Found在请求所指向的 URL 处未找到资源，可能是因为使用了错误的 URL。
429Too Many Requests你的应用已超出 API 请求配额。
500Internal Server ErrorGnip 端发生错误。请使用指数退避策略重试请求。
502Proxy ErrorGnip 端发生错误。请使用指数退避策略重试请求。
503Service UnavailableGnip 端发生错误。请使用指数退避策略重试请求。

​
错误消息

在不同场景下，Engagement API 会返回与情境相关的错误消息，您的应用应能够妥善处理。下表列出了这些错误消息的常见示例及其解读方式。请注意，很多情况下，Engagement API 会在 200 OK 响应中返回可用 data 的部分结果，并附带特定错误消息以提供更多信息。
错误消息说明
"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 端点请求的一个或多个 Tweet ID 超过 90 天，因此无法返回 impressions 或 engagements 指标。
"errors":["Forbidden to access tweets: *TWEET_IDS*"]使用当前认证令牌在代表第三方检索数据时，您请求的一个或多个 Tweet ID 无权访问。