> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# AI agent怎样读取X结果，避免为同一搜索重复付费？

> 按预览、已存结果投影和平台续页区分读取，保留完整文本证据并控制查询预算。

助手只看到 X 搜索的前三条预览时，用同一个 `reference` 和响应返回的 `request_id` 发送 `operation:"result"`，读取这次保存结果里需要的字段。读取已保存的结果不会再查一次 X，所以保存结果仍可读取时，所有额外字段都从保存结果里读。只有需要平台上的另一页时，才用游标发起一次新查询。

例如整理产品问题时，读取同一页全部帖子的 ID、正文和时间，再从原帖里挑短引文。

## 接工具，不是填模型地址

BeatAPI 远程 MCP 地址是 `https://beatapi.io/mcp`，REST 调用发往 `https://api.beatapi.io`。Bearer 密钥放在客户端支持的密钥存储里，或用环境变量引用。不要把真实密钥贴进提示词，也不要提交到代码示例里。按[客户端接入目录](https://beatapi.io/integrations)配置每个客户端，不要假定 Claude、Cursor 和 Codex 用同一种配置语法。

验证连接时，在对话里确认助手能发现搜索、Inspect 和 Run 三类工具，只看到“已连接”徽标还不够。公开的 REST Search 和 Inspect 免费且不需要密钥，所以能查到目录不证明鉴权后的 MCP 执行已经可用。鉴权执行要在你自己的客户端里实测。

例如给客服做新品反馈速览：先看三条预览，确认没有搜错产品，再从已存结果只取帖子 ID、正文和时间。要比较输入开销，让同一个模型先读完整响应，再读同一结果里选出的字段，比较实际输入 token。

## 先选一件X任务，再查真实合同

| 任务     | Reference                                | 关键边界                                                                      |
| ------ | ---------------------------------------- | ------------------------------------------------------------------------- |
| 关键词调研  | `data:twitter.web.fetch_search_timeline` | `keyword`、`search_type:Latest` 或 Top；`data.timeline` 与 `data.next_cursor` |
| 账号近期帖子 | `data:twitter.web.fetch_user_post_tweet` | `screen_name`/`rest_id`，没有竞品式 tab 参数                                      |
| 指定帖的回复 | `data:twitter.web.fetch_post_comments`   | 回复的参数另查，回复输出不能套用搜索 timeline 的结构                                           |

搜索结果有自己的字段，例如 `tweet_id`、`text`、`favorites` 和可为 null 的 `views`。保留这些字段名：不要把 `views` 改称其他服务的 `metrics.views`，也不要假定所有平台的作者、时间和计数含义完全一致。[X搜索指南](/zh/guides/x-search-posts)说明了当前的原始结构和有限导出。

## 一次付费start，不是每换视图都付费搜索

Inspect 价格并批准真实查询后，发送通用的 `capabilities_run` 请求：

```json
{"reference":"data:twitter.web.fetch_search_timeline","operation":"start","input":{"keyword":"<product phrase>","search_type":"Latest"},"view":"preview","max_items":3,"idempotency_key":"<unique-key-for-this-logical-search>"}
```

幂等键按三条规则使用：

* 真正不同的查询或页，用新的幂等键。
* 结果不明的问题解决后，重试同一个逻辑操作时，保持原来的键和相同的输入。不要在超时循环里自动换新键。
* X 搜索是同步能力，不要编写任务状态轮询。

重读已保存的结果不会再查 X。平台下一页按[价格页](https://beatapi.io/zh/pricing)的当前单价计费。`max_items:3` 限制的是预览条数，不是平台返回的条数，也不是计费单位。

## 不重复start，读出已存页每行的正文

1. 检查 `isError`、公开的 error 封装和成功的 action 结果。
2. 成功的预览把主列表提升为 `items`，`items_path` 说明主列表在原结果里的位置。检查实际返回的 `items_total`、`items_shown`、`truncated` 和 `fields_not_found`。这些计数描述的是本次返回的结果和视图，不是 X 全站匹配帖子的总量。
3. 返回的结果读取说明里有 `result_ref` 时，从 `result_ref` 复制真实的 request ID 和到期时间。在到期前，用同一个 BeatAPI 账号请求字段投影：

```json
{"reference":"data:twitter.web.fetch_search_timeline","operation":"result","request_id":"<result_ref.request_id>","view":"full","fields":["items[].tweet_id","items[].text","items[].created_at","items[].favorites","items[].views","data.next_cursor"]}
```

`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 费用。

验收时记录以下各项：

1. 客户端和工具是否可见。
2. Inspect 过的 reference、schema 和价格。
3. 一次逻辑 start 和返回的 request ID。
4. 预览条数和裁剪状态。
5. 用返回的 request ID 实际完成的 result 读取。
6. 投影的行数和缺失字段。
7. 带来源的原句。
8. 用量核对。

没有执行鉴权或 Run 时，如实记下缺口，不要称接入已完成。

## 为什么 full 加 fields 后仍然显示 truncated=true？

`truncated` 表示视图有删减，不专指“少了帖子”。网关的视图实现只要使用 `fields` 投影就会把 `truncated` 标为 true，即使 `items_shown` 等于 `items_total`、选中的正文也完整。不要只因为 `truncated` 为 true 就再付费 start；反过来，行数相等也不证明所有字段齐全。

| 要确认的问题         | 看什么                                                                            |
| -------------- | ------------------------------------------------------------------------------ |
| 已存页是否少展示了行     | 比较 `items_shown` 与 `items_total`；两者都不是全平台数量                                    |
| 预览是否裁掉了字符串/内部值 | 看 `truncation.strings_truncated`、`truncation.item_values_dropped`；摘要不得引用被裁掉的部分 |
| 想要的字段路径是否完全没找到 | `fields_not_found` 列出未命中的路径；先查真实结构，不付费重跑来修字段名                                  |
| 每条都有没有 views   | 逐行检查。`fields_not_found` 不是逐行缺失报告：只要有一项存在该路径，这个路径就不会被列为全部未找到                    |
| 是否收到超过预览预算的结果  | `truncation.over_budget` 是预览字节预算信号，不是精确 token 数，也不证明模型已接受输入                    |

例如同一页三条帖子，一条 `views="100"`，一条 `views=null`，一条没有 `views` 字段。`fields_not_found` 不会为第二条和第三条报出缺失。保留字符串 "100"、null 和缺失这三种状态；只有一条是可解析的数值字符串，不能按三条求平均，更不能把 null 和缺失填成 0。

## 怎么实际减少模型上下文，而不丢证据？

1. 保存原始响应。
2. 只读当前任务需要的 ID、完整正文、时间和指标。
3. 投影仍然过长时，从已保存的本地文件按固定条数分批交给模型，记录每批包含的帖子 ID。**拆本地文件不是翻平台下一页。**
4. 先按 ID 去重。同一 ID 的冲突观察连同来源一起保留，不要静默覆盖。
5. 每个主题汇总都引用帖子 ID 和短原句，并能回查原始文件，而不只是回查模型上一轮的摘要。

比较大小时，使用同一批原始数据、同一个模型分词器和相同的计数范围，分别测量原始文本、投影文本和工具外壳。`truncation.original_bytes` 和 `preview_bytes` 可以辅助判断字节体积，但这两个字节字段不是模型 token 数，也不是费用。不要套用竞品的 95% 节省说法。客户端还可能附加系统消息、工具描述和历史对话，实际账单要另外核对。

来源：网关测试覆盖列表提取、字段投影、未命中路径、预览字节预算，以及同账号完整结果的保存。客户端能否容纳完整的原始响应，取决于具体客户端。

[X问题目录](/zh/faq/x) · [能力合同](/zh/capabilities)