Felo X 帖子搜索

按需要的数据选择接口。五个接口均使用 POST，结果直接位于 JSON 根层级，没有统一的 data 外层。

示例使用总览中配置的 FELO_API_KEY。调用使用平台余额，不使用 Felo Pro 积分。响应示例仅展示结构，实际内容和可选字段会变化。

4. 搜索帖子

POST /api/v1/data/x/tweet/search

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'

返回 tweets、total、has_next 和 next_cursor。帖子包含 id、content、author、created_at 和 metrics，可能嵌套回复、引用或转发的帖子。ID 请按字符串处理。

返回数量边界

limit 是期望收集数量，不保证取满。当前实现按至少 20 条处理：目标为 20 条时读取一页，目标大于 20 条时自动翻页，最多读取 50 页。每轮取页前检查累计时间，超过 60 秒后不再继续取页；正在进行的上游请求可能继续等待，因此这不是整个 HTTP 请求的超时上限。

达到目标、上游没有下一页、返回空页或游标缺失时也会停止。响应少于 limit 不代表请求失败，也不代表已经获取所有匹配帖子；是否继续分页应检查 has_next 和 next_cursor。

{
  "tweets": [{
    "id":"example-post-id",
    "content":"示例帖子内容",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}

分页与费用控制

total 表示本次响应中对应数组的条数；帖子查询的 total 只统计主帖，回复查询则逐组统计。它不是全站匹配总数、帖子完整回复总数或最终计费条数。

1. 首次请求不传 cursor。
2. 读取 has_next 和 next_cursor；查询回复时，读取每个 results 项中的这两个字段。
3. 有下一页且游标非空时，保持查询条件不变，原样传回游标。批量回复需要逐个帖子继续分页。
4. 没有下一页、游标重复，或达到应用自己的页数和费用上限时停止。

分页状态反映上游最后一次返回的状态；达到数量上限后返回的集合可能经过截取。即使 has_next=false，也不能据此承诺已取得 X 上的全部历史或全部回复。应用应展示实际返回条数，避免把有限结果标记为“全部数据”。

每次成功翻页都可能产生费用。五个接口按返回结果条数计费，不是固定的每次请求价格。嵌套回复等记录可能影响计费条数，不要只用最外层数组长度估算费用。请结合当前价格表和控制台用量查看。完整对象字段见 OpenAPI 定义。