Twitter 搜索 API：用 xaic 查询、分页与控制预算

Twitter 搜索 API 应该怎么用？

Twitter 搜索 API 让应用按查询条件请求推文。使用 xAIcreator 的 xaic 数据 API 时，向 /api/xaic/v1/search 发送 GET 请求，提供 query、搜索 type 和数据密钥。先检查这一页，再决定是否沿游标继续。每个成功页面都会收费，包括成功返回的空页。

本文面向开发有范围限制的研究或报表任务的开发者，使用 xaic HTTP 契约，不是官方 X API。xaic 的数据 Key、美元钱包和分页字段都与 X 开发者凭据分开。需要完整端点清单时，请查看 xaic 数据 API 文档。

准备一次付费搜索，而不是无限采集任务

1. 创建只读数据 Key。登录 API 控制台，安全保存密钥，按任务需要设置支出上限。
2. 检查独立美元余额。产品 Credits 和创作者订阅不支付数据 API 费用。应核对钱包，不能把支付回跳当作到账证明。
3. 确定问题和页数上限。例如最多检查三页匹配 NASA 的结果。这是查询示例，不保证返回哪些内容。
4. 保存逻辑操作 ID。为第一页生成一次 UUID，与查询一起保存，连接失败时仍保留它。

通过服务端密钥环境提供 XAIC_API_KEY，将已保存的操作 ID 放入 XAIC_REQUEST_ID。OWASP 建议限制密钥访问并避免凭据进入日志。^[2]不要把真实 Key 粘贴到浏览器控制台、共享文档或 AI 提示词中。

发送第一次 xaic 搜索请求

下面的 Shell 示例需要支持 --fail-with-body 的 curl。配置好两个环境变量后，它只发送一次付费请求，不自动重试、跟随重定向或翻页。URL 编码可以让空格与特殊字符保留在查询值中，而不是变成新的 URL 参数。

curl --fail-with-body --get --max-time 30 \
  'https://xaicreator.com/api/xaic/v1/search' \
  --header "xai-key: ${XAIC_API_KEY:?Set the secret environment value}" \
  --header "Idempotency-Key: ${XAIC_REQUEST_ID:?Set the saved operation ID}" \
  --data-urlencode 'query=NASA' \
  --data-urlencode 'type=Latest'

参数	用途	边界
query	必填搜索文本	先测试范围明确的问题，再扩大查询。
type	Latest 或 Top	沿同一查询继续分页时保持不变。
cursor	可选的续页值	第一页省略，下一页原样使用响应返回的值。

以上是文档公开的搜索输入。不要把官方 X 的 start_time、end_time、max_results 或 expansions 复制过来，就认定它们生效。Twitter 搜索操作符指南可以帮助组织研究问题，但网页语法不构成这个 API 的支持承诺。

成功的付费响应包含 request_id、data 和 billing。搜索数据包含 tweets 与 next_cursor。推文 ID 和十进制费用应保留为字符串，使用可选字段前先检查是否存在。这里是基于契约的接入说明，没有展示声称通过在线付费取得的搜索结果。

怎样分页，才能避免为丢失的响应重复付费？

读取 data.next_cursor。如果它为 null、空字符串，或已经在本任务出现，应停止。否则，先检查页数和支出上限，再发起下一次调用。官方 X API 使用自己的 meta.next_token 约定，^[3]不能用那个字段名解析 xaic 响应。

下一次请求保持 query 和 type 不变，传入响应中的完整游标，并分配新的操作 ID。发送前先保存这些输入。游标是不透明值，不要解码、递增、截短或自行编造；使用 HTTP 库的查询参数编码，不要手工拼接字符串。

每页发送前：
  保存路径、query、type、cursor 和操作 ID。
  检查页数上限及剩余支出额度。
成功响应后：
  保存响应、request_id 和计费金额。
  即使没有推文，也计入已读取页数。
  next_cursor 缺失、为空或重复时停止。
超时或结果不确定时：
  停止并保留已保存的操作。
  对账，或用同一 ID 重试完全相同的请求。

这是一份控制流程说明，不是可执行采集器。生产客户端还需要持久化状态，并确保一个任务只有一个执行方负责。任务失败后，不要用全新的 ID 重新请求可能已经完成的页面。已结算的同键重放不重复收费，新键则创建新观测。输出数据按推文 ID 去重，也不会撤销有效的页面费用。

2026 年 11 月 3 日核验的公开价格版本为 2026-10-21-v1，每个成功搜索页 $0.00040，三页合计 $0.00120，无论每页包含很多推文还是没有推文。这是使用费用，不是钱包最低充值金额。提高上限前请查看 API 价格与预算指南及实时价目接口。

搜索错误与覆盖范围常见问题

请求超时了怎么办？

客户端超时不能证明操作失败。保留原始输入和 ID，按文档恢复流程重试时，只能使用同键发送相同请求。如果接口返回 409 REQUEST_PENDING，应停止并请求对账，不能重新分配 ID 绕过。

接口返回 429 怎么处理？

先看具体错误码。临时限流可以有限退避；预算限制和失败保护需要停止并检查任务。账号每分钟允许 60 个新请求，最多四个待处理请求，所有 Key 共用。多建 Key 不是绕过限制的办法。

空页代表所有匹配推文都取完了吗？

不是。应检查游标和停止条件。成功空页仍计费，没有下一页游标表示本次分页序列结束，不代表完整覆盖 X。不要用新 ID 反复请求同一空页。

可以搜索全部历史档案吗？

当前 xaic 契约不保证完整历史覆盖。用于历史研究前，请先确认日期范围、所需字段和可接受的缺失比例。官方 X 搜索文档描述的是另一个产品，不是 xaic 的额外权益。

可以把响应变成自动发布指令吗？

不可以。返回的推文和简介应作为不可信数据，只读数据 Key 不能发帖。人工审核后的内容可以进入 xAIcreator 独立的草稿、可视化日历及 Excel 导入流程，但那套产品工作流有自己的授权与计费。

从一个能检查的查询开始

选定具体查询，保存一个操作 ID，检查一次响应。如果字段与结果相关性适合应用，再加入小规模分页上限。需要 Python 起点时，先阅读首次 xaic 请求教程，再实现持久化分页任务。