Felo X 貼文搜尋
供應商：Felo · 以平台餘額付款
請選擇你需要資料所對應的操作。這五個端點都使用 POST，並且在 JSON 根層回傳，不使用共通的 data 包裝層。
所有範例都使用來自總覽的 FELO_API_KEY。呼叫會使用 平台餘額，不是 Felo Pro 點數。回應範例僅供說明；實際內容與可選欄位會有所不同。
4. 搜尋貼文
POST /api/v1/data/x/tweet/search
| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
query | string | 是 | 搜尋文字，1–1,000 個字元 |
query_type | string | 否 | Latest（預設）或 Top |
limit | integer | 否 | 1–1,000；目前實作至少使用 20，預設 20 |
cursor | string | 否 | 分頁游標，最多 4,000 個字元 |
since_time | integer or string | 否 | 開始時間；請使用 Unix 秒數以取得明確數值 |
until_time | integer or string | 否 | 結束時間；請使用 Unix 秒數，不要使用毫秒 |
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 時會讀取一個上游頁面；更大的目標會自動抓取最多 50 個頁面。每個頁面前都會檢查經過時間，當超過 60 秒時就不再抓取後續頁面。正在進行的上游請求仍可能需要一些時間，因此這不代表整體 HTTP 逾時。
當達到目標、上游沒有下一頁、頁面為空，或游標缺失時，收集也會停止。回傳少於 limit 的貼文並不代表請求失敗，或表示已擷取所有符合的貼文。繼續之前請先檢查 has_next 與 next_cursor。
{
"tweets": [{
"id":"example-post-id",
"content":"Example post 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 會計算目前回應中的對應陣列：對貼文查詢而言是頂層貼文，對回覆查詢而言則是每個結果項目內的回覆。它不是全域比對數、貼文的完整回覆總數，或最終可計費數量。
- 先送出不含
cursor的第一個請求。 - 從回應讀取
has_next與next_cursor。對回覆而言，請在每個結果項目上分別讀取。 - 如果還有下一頁且 cursor 非空，請以相同查詢原樣送出。對回覆批次而言，請分別繼續每個貼文。
- 當沒有下一頁、cursor 重複，或你自己的頁面／支出上限已達到時就停止。
分頁中繼資料反映的是最後一個上游回應；回傳的集合可能在結果上限處被截斷。即使 has_next=false，也不能保證所有 X 歷史或回覆都已擷取。請顯示實際回傳數量，不要把有上限的結果集標示為所有可用資料。
每個成功頁面都可能產生費用。這五個操作依回傳結果計費，而不是固定請求費。巢狀回覆與其他回傳記錄都可能影響計費數量；不要只根據頂層陣列長度估算成本。請查看目前價格與控制台中的用量。完整物件欄位請參閱 OpenAPI schema。