跳转到主要内容
搜索 Post 是一项重要功能，可用来呈现围绕特定主题或事件的 X 上的讨论。虽然 X 本身提供了此功能，但这些端点在筛选与摄取 Post 时具备更高的灵活性与能力，帮助你更轻松地为研究找到相关数据，构建近实时的“监听”类应用，或更全面地探索、分析并/或对与关注主题相关的 Post 采取行动。  我们提供两个用于搜索 Post 的端点：最近搜索与全量归档搜索。这两个 REST 端点采用一致的设计与特性，包括使用单一搜索查询来筛选围绕特定主题的 Post。这些搜索查询由一组运算符构成，用于匹配 Post 和用户属性，例如消息关键词、话题标签（hashtags）和 URL。你可以使用布尔逻辑与括号将运算符组合成查询，以进一步细化匹配行为。  最近搜索与全量归档搜索端点都会返回编辑相关的 Post 元数据。自 2022 年 9 月 29 日起创建的所有 Post 对象，均包含 Post 编辑元数据，即便该 Post 从未被编辑。每次编辑 Post，都会生成一个新的 Post ID。某个 Post 的编辑历史以一个 Post ID 数组记录，起始为原始 ID。 这些端点将始终返回最新的编辑版本，并包含任何编辑历史。在 30 分钟编辑窗口之后收集到的任何 Post 都代表其最终版本。要了解更多有关编辑 Post 元数据的信息，请参阅编辑 Post 基础知识页面。 在你设置好查询并开始接收 Post 后，这些端点支持按时间以及 Post ID 区间来浏览结果，旨在支持两个常见用例： 
  • 以历史为主：请求聚焦于特定时间段，对数据的实时性不作要求。仅发起一次请求，并按需通过分页返回所有匹配数据。这是 Search Posts 的默认模式。
  • 轮询或监听：以“自上次请求以来是否有新 Post？”的方式持续发起请求，通常用于对感兴趣的 Post 进行近实时“监听”的场景。
许多运算符与查询上限仅对企业版访问开放，这意味着你必须使用位于具备企业版访问权限的Project中的某个 App 的密钥与令牌进行调用，方可使用这些附加功能。你可在下方的端点章节了解更多信息。 最近搜索与全量归档搜索端点返回的 Post 都会计入每月的Post 上限。 账户设置 要访问这些端点，你需要： 请在我们的入门指南中了解更多关于获取 X API v2 端点访问的信息。 “最近搜索”端点允许你以编程方式访问过去一周内发布的、经过筛选的公开 Post。凡拥有开发者账号，并在某个Project中的应用使用其密钥和令牌的开发者均可使用。 你可以使用OAuth 1.0a 用户上下文、OAuth 2.0 App-Only或OAuth 2.0 授权码（PKCE）对请求进行认证。不过，如果你希望在 Post 结果中获取私有指标，或区分有机与推广的指标，则必须使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE），并传递与发布该内容的用户关联的用户访问令牌（Access Tokens）。 该端点每个请求最多可按时间倒序返回 100 条 Post，并提供用于遍历大量匹配 Post 的分页令牌。 当你使用常规访问级别的 Project 时，可以使用基础运算符，且查询最长为 512 个字符。使用企业版访问级别的 Project 时，可使用更多运算符；具有企业版访问的 Project 可发起最长 4096 个字符的查询。 了解更多访问级别。 v2 全量归档搜索端点仅向具有 Pro 访问权限和 企业版 访问权限的项目开放。该端点允许你根据搜索查询，以编程方式访问自 2006 年 3 月首条 Post 起完整归档中的公开 Post。 你可以使用 OAuth 2.0 App-Only 对该端点的请求进行认证，且 App Access Token 必须来自所属项目具备 Pro 或企业版访问权限的应用。由于无法使用此端点代表其他用户发起请求（OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE）），因此你将无法获取私有 metrics。 该端点每次请求最多可按时间逆序返回 500 条 Post，并提供用于翻页的 分页 令牌，以便浏览大量匹配的 Post。 注意：如果通过 tweet.fields 参数请求 annotations，max_results 参数当前的最大值为 100。该限制将来可能会变更，请留意这一点。 由于此端点仅对已获批 Pro 和企业版访问权限的用户开放，你可以使用完整的搜索 operators，并可构建最长 1024 个字符的查询。







支持资源 了解如何使用 Postman 发起请求 排查错误 访问 API 参考页面