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







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