> 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.

# 搜索成功但 timeline 为空，是接口坏了吗？

> twitter.web.fetch_search_timeline 返回成功且 data.timeline: [] 表示该页搜索命中零条帖子而非接口故障，应先核对 HTTP 状态、error 与 request_id。

不是。`twitter.web.fetch_search_timeline` 请求成功且返回 `data.timeline: []`，说明该页搜索命中零条帖子，并不等于接口故障。先核对 HTTP 状态与 `status` 字段，再确认 `data.timeline`；如果 `data.timeline` 缺失或请求失败，请查看完整响应和 `request_id`。搜索品牌名或产品型号得到空时间线时，先检查拼写和筛选条件，把更简单的搜索词作为一次独立搜索执行。

## 诊断已经保存的响应

1. 使用 `/v1/social-data/call` 返回的完整直接响应，不要使用 AI 的简短预览。
2. 从已保存的响应头读取实际 HTTP 状态码。
3. 把下面的脚本保存为 `diagnose_x_search.py`。
4. 运行 `python3 diagnose_x_search.py x-search-page-1.json 200 diagnosis.json`，将 `200` 替换为实际 HTTP 状态码。

`diagnose_x_search.py` 不发起网络请求，不修改原始响应文件，只新建 `diagnosis.json`。脚本打印的状态用于分类诊断结果，不代表采集成功。

```python
import hashlib
import json
import sys
from pathlib import Path

source, http_text, target = sys.argv[1:]
http = int(http_text)
if not 100 <= http <= 599: raise ValueError('Use the actual HTTP status from the saved headers')
source, target = Path(source), Path(target)
raw = source.read_bytes()
report = {'http_status': http, 'source_file': str(source.resolve()), 'source_sha256': hashlib.sha256(raw).hexdigest(),
    'network_calls': 0, 'automatic_retry': False, 'next_page_executed': False}
try:
    result = json.loads(raw)
except (ValueError, UnicodeDecodeError):
    result = None
if http != 200:
    report.update(state='http_failure', next_step='Inspect saved HTTP headers and error; do not classify this as an empty search')
elif not isinstance(result, dict):
    report.update(state='unreadable_response', next_step='Keep the original bytes; obtain the full direct JSON, not an HTML page or preview')
elif result.get('status') == 'failed' or result.get('error') is not None:
    report.update(state='reported_failure', next_step='Inspect the actual error code and request ID before any separately approved retry')
elif result.get('status') != 'succeeded' or result.get('action') != 'twitter.web.fetch_search_timeline':
    report.update(state='wrong_response', next_step='Use the successful direct response of twitter.web.fetch_search_timeline')
elif not isinstance(result.get('request_id'), str) or not result['request_id'].strip():
    report.update(state='missing_request_id', next_step='Keep the response; source identity is missing')
else:
    data = result.get('data')
    items = data.get('timeline') if isinstance(data, dict) else None
    if not isinstance(items, list):
        report.update(state='missing_timeline_array', next_step='Do not substitute an absent or redacted field with []; inspect the original shape')
    elif data.get('next_cursor') is not None and not isinstance(data['next_cursor'], str):
        report.update(state='invalid_cursor', next_step='Retain the posts but do not invent or follow a cursor')
    else:
        invalid = []
        ids = []
        for n, item in enumerate(items):
            value = item.get('tweet_id') if isinstance(item, dict) else None
            if not isinstance(value, str) or not value.isascii() or not value.isdigit() or not any(c != '0' for c in value):
                invalid.append(n)
            else:
                ids.append(value)
        if invalid:
            report.update(state='unusable_timeline_ids', invalid_item_indices=invalid, next_step='Keep raw items; a missing, numeric or redacted ID is not an empty result')
        else:
            report.update(state='empty_timeline' if not items else 'usable_timeline', returned_items=len(items), unique_ids=len(set(ids)),
                has_nonblank_cursor=bool((data.get('next_cursor') or '').strip()),
                next_step='Review the original phrase and search_type; do not repeat or paginate automatically' if not items else 'Use the saved-page exporter without purchasing page one again')
if isinstance(result, dict):
    error = result.get('error')
    error = error if isinstance(error, dict) else {}
    request_id = result.get('request_id') or error.get('request_id')
    if isinstance(request_id, str) and request_id.strip(): report['request_id'] = request_id
    if isinstance(error.get('code'), str): report['error_code'] = error['code']
with target.open('x', encoding='utf-8') as f:
    json.dump(report, f, ensure_ascii=False, indent=2)
print(report['state'])
```

## 不同诊断结果，下一步分别做什么？

| 状态                                                                | 下一步                                                                     |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `empty_timeline`                                                  | 核对已存请求中的精确 `keyword` 与 `search_type`。记录「该查询在该时间返回 0 行」，不要据此推断全站总提及数为 0。 |
| `usable_timeline`                                                 | 直接在本地导出已存页；重新运行采集请求会再次付费购买第一页。                                          |
| `http_failure` 或 `reported_failure`                               | 查看实际响应头、错误码与 `request_id`，按错误码定位鉴权、余额、限流或服务问题并修复后再决定是否重试。               |
| `unreadable_response`、`wrong_response` 或 `missing_timeline_array` | 获取完整的直接响应并修正输入文件，继续翻页无法修复截断的包装体或解析器问题。                                  |
| `missing_request_id`、`invalid_cursor` 或 `unusable_timeline_ids`   | 保留原始响应以供排查，不编造 ID、不把占位符当正文，也不自行构造续页游标。                                  |

`diagnose_x_search.py` 检查响应信封、`data.timeline` 数组以及可用的 `tweet_id` 字符串，不核实帖子内容真假，也不校验每个互动指标字段；字段级校验由搜索指南中的 CSV 导出器完成。`diagnosis.json` 中的 `source_sha256` 哈希用于把诊断报告与本地响应字节关联起来，不是服务器签名回执。

## 要不要放宽关键词，或者改成 Latest？

修改任何参数前先核对已保存的原请求。搜索词填入 `keyword`，`search_type` 默认为 `Top`。`Latest` 只请求最新排序，不会让空搜索变成全量结果，也不保证覆盖特定日期范围。仅当能够明确指出具体修正项（如拼写错误、品牌名写错或误加限制条件）时再调整查询，并将原零行观察与新查询分开记录，各自保留参数与采集时间，不混入同一分页链。

更换关键词、切换 `search_type` 与请求下一页各自按一次独立收费请求计费。批准新请求前先在 `/v1/capabilities/inspect` 查看 `data:twitter.web.fetch_search_timeline` 的当前价格，不要为拿到非空页自动尝试大量变体。如果空页仍返回游标，`diagnosis.json` 会记录 `has_nonblank_cursor`；`diagnose_x_search.py` 不会跟随该游标，且下一页仍可能返回零条匹配。

[已存页导出CSV](/zh/guides/x-search-posts) · [Latest与Top](/zh/faq/x-search-order) · [X问题](/zh/faq/x)

免费合同参考：`data:twitter.web.fetch_search_timeline`。