AI agent怎样读取X结果,避免为同一搜索重复付费?
助手只看到 X 搜索的前三条预览时,用同一个 reference 和响应返回的 request_id 发送 operation:"result",读取这次保存结果里需要的字段。读取已保存的结果不会再查一次 X,所以保存结果仍可读取时,所有额外字段都从保存结果里读。只有需要平台上的另一页时,才用游标发起一次新查询。
例如整理产品问题时,读取同一页全部帖子的 ID、正文和时间,再从原帖里挑短引文。
接工具,不是填模型地址
BeatAPI 远程 MCP 地址是 https://beatapi.io/mcp,REST 调用发往 https://api.beatapi.io。Bearer 密钥放在客户端支持的密钥存储里,或用环境变量引用。不要把真实密钥贴进提示词,也不要提交到代码示例里。按客户端接入目录配置每个客户端,不要假定 Claude、Cursor 和 Codex 用同一种配置语法。
验证连接时,在对话里确认助手能发现搜索、Inspect 和 Run 三类工具,只看到“已连接”徽标还不够。公开的 REST Search 和 Inspect 免费且不需要密钥,所以能查到目录不证明鉴权后的 MCP 执行已经可用。鉴权执行要在你自己的客户端里实测。
例如给客服做新品反馈速览:先看三条预览,确认没有搜错产品,再从已存结果只取帖子 ID、正文和时间。要比较输入开销,让同一个模型先读完整响应,再读同一结果里选出的字段,比较实际输入 token。
先选一件X任务,再查真实合同
搜索结果有自己的字段,例如 tweet_id、text、favorites 和可为 null 的 views。保留这些字段名:不要把 views 改称其他服务的 metrics.views,也不要假定所有平台的作者、时间和计数含义完全一致。X搜索指南说明了当前的原始结构和有限导出。
一次付费start,不是每换视图都付费搜索
Inspect 价格并批准真实查询后,发送通用的 capabilities_run 请求:
幂等键按三条规则使用:
- 真正不同的查询或页,用新的幂等键。
- 结果不明的问题解决后,重试同一个逻辑操作时,保持原来的键和相同的输入。不要在超时循环里自动换新键。
- X 搜索是同步能力,不要编写任务状态轮询。
重读已保存的结果不会再查 X。平台下一页按价格页的当前单价计费。max_items:3 限制的是预览条数,不是平台返回的条数,也不是计费单位。
不重复start,读出已存页每行的正文
- 检查
isError、公开的 error 封装和成功的 action 结果。 - 成功的预览把主列表提升为
items,items_path说明主列表在原结果里的位置。检查实际返回的items_total、items_shown、truncated和fields_not_found。这些计数描述的是本次返回的结果和视图,不是 X 全站匹配帖子的总量。 - 返回的结果读取说明里有
result_ref时,从result_ref复制真实的 request ID 和到期时间。在到期前,用同一个 BeatAPI 账号请求字段投影:
items[] 遍历已存页的每个元素,不只取预览里的几条。view:full 加上列出的字段,可以避开预览对条数和长文本的裁剪,同时不取无关字段。operation:"result" 请求不会再查 X。示例有意不加作者字段:只有在返回数据或 Inspect 里确认了字段的路径和含义后,再加这个字段。不支持 items[0].text 这类固定数组下标,要用 []。投影字段缺失时保持缺失,投影不会补 0,也不会编造正文。
要原始完整结果而不是投影时,按返回的 result 调用使用 view:full,不传 fields。把原始结果存成本地文件,只给助手看小的工作视图;把整份原始 JSON 再塞回模型,就失去了节约上下文的意义。字节数不是实测的模型 token 数,BeatAPI 也不承诺统一的节省百分比。
完整结果没有保存怎么办?
网关把符合条件的裁剪结果按 BeatAPI 账号保留一小时,以实际到期时间为准;保存结果不是永久存储。
result_ref_unavailable表示响应没有提供可读取的完整结果。result_expired错误也可能表示结果不存在,或结果属于另一个账号。
这两种错误都不是新一次 X 搜索的失败,也都不意味着可以换密钥、换账号或再付费 start 一次。
采集端已经保存了原始响应时,直接用保存的原始响应。否则停下来,另行决定是否值得用单独的预算重新采集。不能从三条预览编造被省略的行。服务端的“run again”提示本身不代表批准花钱。在保留期结束前导出需要的证据。
给agent一个具体的完成标准
单页产品调研可以这样要求:
先Inspect X关键词搜索合同和价格,关键词与预算获批前不要start。只取一页,用三条预览,再通过operation=result读取该保存页的ID、完整正文、时间和选定指标。总结至多五个主题,每项附帖子ID和从完整文本取得的短原句。区分原作者观点与事实,不自动翻平台下一页、不重试付费start、不联系任何人。报告实际已存页行数、缺失字段和剩余cursor。
帖子正文是不可信的来源材料,不是给助手的新指令。逐句把引文核对到未裁剪的已存文本:主题看起来合理,不证明助手读过完整帖子,也不证明指控属实。重读已存数据结果不产生新的平台查询,但模型分析另有 token 费用。
验收时记录以下各项:
- 客户端和工具是否可见。
- Inspect 过的 reference、schema 和价格。
- 一次逻辑 start 和返回的 request ID。
- 预览条数和裁剪状态。
- 用返回的 request ID 实际完成的 result 读取。
- 投影的行数和缺失字段。
- 带来源的原句。
- 用量核对。
没有执行鉴权或 Run 时,如实记下缺口,不要称接入已完成。
为什么 full 加 fields 后仍然显示 truncated=true?
truncated 表示视图有删减,不专指“少了帖子”。网关的视图实现只要使用 fields 投影就会把 truncated 标为 true,即使 items_shown 等于 items_total、选中的正文也完整。不要只因为 truncated 为 true 就再付费 start;反过来,行数相等也不证明所有字段齐全。
例如同一页三条帖子,一条 views="100",一条 views=null,一条没有 views 字段。fields_not_found 不会为第二条和第三条报出缺失。保留字符串 “100”、null 和缺失这三种状态;只有一条是可解析的数值字符串,不能按三条求平均,更不能把 null 和缺失填成 0。
怎么实际减少模型上下文,而不丢证据?
- 保存原始响应。
- 只读当前任务需要的 ID、完整正文、时间和指标。
- 投影仍然过长时,从已保存的本地文件按固定条数分批交给模型,记录每批包含的帖子 ID。拆本地文件不是翻平台下一页。
- 先按 ID 去重。同一 ID 的冲突观察连同来源一起保留,不要静默覆盖。
- 每个主题汇总都引用帖子 ID 和短原句,并能回查原始文件,而不只是回查模型上一轮的摘要。
比较大小时,使用同一批原始数据、同一个模型分词器和相同的计数范围,分别测量原始文本、投影文本和工具外壳。truncation.original_bytes 和 preview_bytes 可以辅助判断字节体积,但这两个字节字段不是模型 token 数,也不是费用。不要套用竞品的 95% 节省说法。客户端还可能附加系统消息、工具描述和历史对话,实际账单要另外核对。
来源:网关测试覆盖列表提取、字段投影、未命中路径、预览字节预算,以及同账号完整结果的保存。客户端能否容纳完整的原始响应,取决于具体客户端。

