設定 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 不足，無法完成請求