Felo API (harness)

X Search API

搜索 X 用户、tweets、时间线和回复，并返回分页元数据。

POST/v2/x/tweet/search

认证

Bearer API key

Content type

application/json

限流说明

1 request per 10 seconds, 3 per minute, 10 per 10 minutes.

Chat API

X Search API 可访问 X/Twitter 数据，包括用户资料、用户搜索、用户 tweets、tweet 搜索和回复。适合 Agent 研究、舆情监听、账号分析和内容洞察。

认证

Authorization: Bearer YOUR_API_KEY

1. 获取用户信息

按用户名批量获取 X 用户资料。

POST https://openapi.felo.ai/v2/x/user/info

参数	类型	必填	说明
`usernames`	array of strings	是	要查询的 X 用户名列表

curl -X POST 'https://openapi.felo.ai/v2/x/user/info' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"usernames":["elonmusk","OpenAI"]}'

2. 搜索用户

按关键词搜索 X 用户。

POST https://openapi.felo.ai/v2/x/user/search

参数	类型	必填	说明
`query`	string	是	搜索关键词
`cursor`	string	否	上一页响应返回的分页 cursor

3. 获取用户 Tweets

获取指定 X 用户发布的 tweets。

POST https://openapi.felo.ai/v2/x/user/tweets

参数	类型	必填	说明
`x_user_id`	string	否	X 用户 ID；`x_user_id` 和 `username` 二选一
`username`	string	否	X 用户名；`x_user_id` 和 `username` 二选一
`limit`	integer	否	返回结果数量
`cursor`	string	否	上一页响应返回的分页 cursor
`include_replies`	boolean	否	是否包含回复

curl -X POST 'https://openapi.felo.ai/v2/x/user/tweets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"username":"elonmusk","limit":20}'

4. 搜索 Tweets

按关键词搜索 X tweets，并支持高级查询语法。

POST https://openapi.felo.ai/v2/x/tweet/search

参数	类型	必填	说明
`query`	string	是	搜索查询，支持高级搜索语法
`query_type`	string	否	查询类型筛选
`since_time`	integer	否	开始时间筛选，Unix 秒级时间戳
`until_time`	integer	否	结束时间筛选，Unix 秒级时间戳
`limit`	integer	否	返回结果数量
`cursor`	string	否	上一页响应返回的分页 cursor

5. 获取 Tweet 回复

获取指定 tweets 的回复。

POST https://openapi.felo.ai/v2/x/tweet/replies

参数	类型	必填	说明
`tweet_ids`	array of strings	是	要获取回复的 Tweet ID
`cursor`	string	否	上一页响应返回的分页 cursor
`since_time`	integer	否	开始时间筛选，Unix 秒级时间戳
`until_time`	integer	否	结束时间筛选，Unix 秒级时间戳

通用响应字段

字段	类型	说明
`total`	integer	返回或可用的结果数量
`has_next`	boolean	是否还有更多结果
`next_cursor`	string	下一页 cursor
`users`	array	用户 endpoint 返回的用户对象
`tweets`	array	tweet endpoint 返回的 tweet 对象
`results`	array	回复 endpoint 返回的结果对象

用户对象可能包含 user_id、username、display_name、description、followers_count、following_count、tweet_count、verified、blue_verified、profile_image_url、created_at、location 和 url。

Tweet 对象可能包含 id、content、author、created_at、metrics、conversation_id、media_urls、hashtags、mentions、urls、url、lang、回复字段、quoted tweet 和 retweeted tweet。

Credits 与限流

每次 API 调用会根据返回结果数量扣除 credits。如果请求返回 0 条结果，则不扣除 credits。发起任何 X API 请求前，账户至少需要 10 credits。

Endpoint	Credit 成本
`POST /x/user/info`	每返回 1 个用户扣 1 credit
`POST /x/user/search`	每返回 1 个用户扣 1 credit
`POST /x/user/tweets`	每返回 1 条 tweet 扣 1 credit
`POST /x/tweet/search`	每返回 1 条 tweet 扣 1 credit
`POST /x/tweet/replies`	每返回 1 条回复扣 1 credit

credits 余额低于 100 的非付费订阅账户会受到限流。触发限流时，API 返回 HTTP 429，Retry-After header 会提示建议等待秒数。

错误码

Code	HTTP Status	说明
`INVALID_API_KEY`	401	API key 无效或已撤销
`X_SEARCH_FAILED`	400/500	X search 请求失败；请检查参数或下游错误
`RATE_LIMIT_EXCEEDED`	429	请求过多；请稍后重试
`insufficient_credits`	402	credits 不足，无法完成请求