跳到导航

搜索成功但 timeline 为空,是接口坏了吗?

不是。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。脚本打印的状态用于分类诊断结果,不代表采集成功。

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 · Latest与Top · X问题

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