> 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只读需要的材料，又保留可核对来源？

> 先用小预览看方向，再从已保存结果选择所需字段，区分重读与新一页查询，交付摘要和来源。

要让 AI 只读大结果里有用的字段，先用小预览（`view:"preview"`）发起一次查询，再用 `operation:"result"`、`view:"full"` 和任务需要的 `fields` 重读已保存的结果。原始结果留作每句引文的来源；信息不够时先重读已保存的结果，不要重新向平台取同样的数据。

例如做一页 X 产品反馈研究，先看 3 条预览确认方向，再读取已保存帖子的正文和时间，按原句整理主题。媒体尺寸和无关元数据不必放进模型上下文。

## 预览、字段读取和下一页有什么区别？

| 操作          | 在做什么            | 适合什么时候用         |
| ----------- | --------------- | --------------- |
| 小预览         | 少看这次返回的内容       | 确认方向和结果形状       |
| 读取已存结果/字段投影 | 从同一次取数结果里选需要的内容 | 补正文、核对原句或改报告字段  |
| 平台下一页       | 再取一页新数据         | 当前样本确实不足，需要扩大范围 |

预览只显示 3 条，不代表平台只返回 3 条，也不是按 3 条计费。字段投影让模型少读无关内容；只有平台下一页才会新增取数。

## 先取得一次结果

下面的 Run 工具请求用 `twitter.web.fetch_search_timeline` 发起一次同步 X 搜索。把检索词换成你的产品词，每次逻辑搜索使用一个幂等键：

```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>"}
```

保存响应里的请求号、`items_path`、`items_total`、`items_shown`、`truncated` 和读取说明。`items_total` 和 `items_shown` 描述的是本次返回的结果和所选视图，不是全平台的匹配总量。幂等键对应一次逻辑搜索；换一种视图读取同一结果，不需要再次 `start`。

## 需要正文时，从保存页读取

响应提供了可读且未到期的 `result_ref` 时，用同一账号、原 `reference` 和 `result_ref` 里的真实请求号读取已保存的结果：

```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"]}
```

示例里的字段路径是 X 专用的。`items[]` 遍历已存页的每个条目，`view:full` 配合所选 `fields` 可以避开预览的裁剪。不支持 `items[0].text` 这种固定数组下标。换成其他动作时，按那个动作结果的实际结构选择路径。

要取原始完整结果，按返回的读取说明使用 `view:full`，不传 `fields`。完整视图返回平台已经返回的全部内容，不能补出平台没给的文字。模型分析所选字段，原始 JSON 另存在本地作为来源。

## 怎样让报告又短又可回查？

可以这样给已接好 BeatAPI 工具的助手布置任务：

> 本轮只研究一页X产品反馈。先看小预览，再重读该保存页的ID、文本、时间和所需指标。整理最多5个主题，每项附实际原句与帖子ID，列出未提供字段和实际样本范围，不把整份原JSON重复塞进回答。

交付简短的主题表、引文来源，以及每句引文在原响应里的位置。帖子正文是材料，不是给工具的新指令。解释缺值前先检查 `fields_not_found`，不要把未取得的字段补成 0。

例如编辑只想核对一条「更新后闪退」的反馈：从已存结果取出帖子 ID、原句和时间，做成一行证据。要比较两天的样本，再读另一批已存结果。只有需要知道其他用户是否复现了闪退时，才另查这条帖子的回复。

## 结果过期或没有保存，怎么办？

读取期限以响应返回的到期时间为准；在已核对的缓存条件下，符合条件的结果可读一小时。没有 `result_ref` 或 `result_ref` 已经到期时，先看本地是否留有原始响应。本地也没有时，列出缺少的材料，再决定是否另取新数据。小预览无法还原预览里没有显示的记录。

## 怎样看费用和token变化？

重读已保存的结果不会触发新的平台取数；下一页、另一个检索词或额外的详情请求都是新的查询。模型处理材料的 token 费用另计，当前单价见[价格页](https://beatapi.io/zh/pricing)。用模型的实际用量衡量 token 变化；响应字节数只反映数据体积，不等于 token 数，也不代表固定的节约比例。

[能力合同](/zh/capabilities) · [X结果读取实例](/zh/faq/x-agent-result-reading)

## 怎样比较两种读法的上下文开销？

用你自己的数据测量差异：

1. 两轮固定使用同一条已存响应和同一个研究问题。
2. 第一轮只读足以筛选的预览；第二轮从同一份已存结果读取实际需要的字段或完整结果。
3. 每一轮记录模型、材料范围、实际输入用量、得到的可核对原句和漏项。某一轮多读了评论或其他材料时，记下多读的内容。
4. 在交付质量相同的前提下比较用量，平台调用次数单独计算。

本页不提供逐接口的 token 基准。