# X 資料

擷取 X 個人檔案、搜尋使用者與貼文，並對時間軸與回覆進行分頁。

請選擇你需要資料所對應的操作。這五個端點都使用 POST，並且在 JSON 根層回傳，不使用共通的 `data` 包裝層。

所有範例都使用來自[總覽](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-overview.md)的 `FELO_API_KEY`。呼叫會使用 **平台餘額**，不是 Felo Pro 點數。回應範例僅供說明；實際內容與可選欄位會有所不同。

## 選擇操作

| 需求 | 端點 |
|---|---|
| 已知使用者名稱的個人檔案 | `POST /api/v1/data/x/user/info` |
| 依搜尋查詢找使用者 | `POST /api/v1/data/x/user/search` |
| 單一使用者的貼文 | `POST /api/v1/data/x/user/tweets` |
| 符合查詢的貼文 | `POST /api/v1/data/x/tweet/search` |
| 已知貼文的回覆 | `POST /api/v1/data/x/tweet/replies` |

## 1. 取得使用者個人檔案

`POST /api/v1/data/x/user/info`

| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
| `usernames` | string array | 是 | 1–100 個使用者名稱；請傳送不含 `@` 的帳號 |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'
```

回應包含 `users` 與 `total`。每位使用者都包含 `user_id`、`username` 與 `display_name`；也可能包含個人檔案文字、追蹤者數、驗證狀態及其他中繼資料。一批請求回傳的個人檔案數量可能少於要求值。請依 username 或 ID 配對，不要依陣列位置。

```json
{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}
```

## 2. 搜尋使用者

`POST /api/v1/data/x/user/search`

| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
| `query` | string | 是 | 1–1,000 個字元 |
| `cursor` | string | 否 | 分頁游標，最多 4,000 個字元 |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'
```

回應包含 `users`、`total`、`has_next` 與 `next_cursor`。這個操作沒有 `limit` 參數。

```json
{"users":[],"total":0,"has_next":false,"next_cursor":null}
```

## 3. 取得使用者時間軸

`POST /api/v1/data/x/user/tweets`

| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
| `username` | string | 需要一個識別碼 | 使用者帳號，最多 100 個字元 |
| `x_user_id` | string | 需要一個識別碼 | 使用者 ID，最多 100 個字元；優先於 `username` |
| `limit` | integer | 否 | 1–1,000；目前實作至少使用 20，預設 20 |
| `cursor` | string | 否 | 分頁游標，最多 4,000 個字元 |
| `include_replies` | boolean | 否 | 包含巢狀回覆；預設 `false` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'
```

回應包含 `tweets`、`total`、`has_next` 與 `next_cursor`。將 `limit` 設得低於 20，並不能保證回傳項目會更少或費用更低。包含回覆可能增加回傳資料與可計費結果。

### 結果與巢狀回覆限制

`limit` 是這次請求的頂層貼文目標數量，不是保證回傳的結果數。現行實作使用至少 20 的目標：目標為 20 時會讀取一個上游頁面；更大的目標會自動抓取最多 50 個頁面。每讀取一個頁面之前，系統會檢查經過時間，當超過 60 秒時就停止進一步抓取頁面。這項檢查不能保證整個 HTTP 請求會在 60 秒內完成。

當達到目標、上游沒有下一頁、頁面為空，或游標缺失時，收集也會停止。因此，一個成功回應可能包含少於 `limit` 的貼文。當可用時，請使用 `has_next` 與 `next_cursor` 繼續。

在 `include_replies=true` 時，每個回傳貼文最多會再取得 5 個額外頁面，且最多 100 則巢狀回覆。當沒有下一頁、頁面為空，或游標無法前進時，收集可能更早停止。這些巢狀回覆不屬於頂層 `limit` 與 `total`，但可能增加可計費結果。

巢狀 `replies` 不是完整的回覆封存，也不會為這些額外收集曝光獨立的延續游標。若要獨立分頁回覆，請使用 Read replies 操作及其回傳的游標。不要把頂層貼文游標重用於回覆。

## 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 秒數，不要使用毫秒 |

```bash
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`。

```json
{
  "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
}
```

## 5. 讀取回覆

`POST /api/v1/data/x/tweet/replies`

| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
| `tweet_ids` | string or string array | 是 | 一個貼文 ID，或最多 20 個 ID 的批次 |
| `cursor` | string | 否 | 最多 4,000 個字元；與單一貼文 ID 搭配使用 |
| `since_time` | integer | 否 | Unix 秒數格式的開始時間 |
| `until_time` | integer | 否 | Unix 秒數格式的結束時間 |

將佔位符替換為真實的貼文 ID：

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'
```

與時間軸和貼文搜尋不同，回覆會分組在 `results` 底下。每個項目都有自己的分頁狀態：

```json
{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}
```

### 每次請求的回覆限制

每次請求會為每個 `tweet_id` 讀取一個上游回覆頁面，並最多保留 100 則回覆；它不會自動抓取每一頁回覆。在最多 20 個 ID 的批次中，100 則回覆上限會分別套用到每個 `results` 項目。實際數量可能更少。

每個項目的 `total` 是該項目回傳的回覆數量，而不是該貼文的完整回覆總數。若要繼續，請使用該項目的 `next_cursor`，並在下一個請求中只傳送其單一貼文 ID。沒有 `limit` 參數可提高每次請求的上限。

## 分頁與成本控制

`total` 會計算目前回應中的對應陣列：對貼文查詢而言是頂層貼文，對回覆查詢而言則是每個結果項目內的回覆。它不是全域比對數、貼文的完整回覆總數，或最終可計費數量。

1. 先送出不含 `cursor` 的第一個請求。
2. 從回應讀取 `has_next` 與 `next_cursor`。對回覆而言，請在每個結果項目上分別讀取。
3. 如果還有下一頁且 cursor 非空，請以相同查詢原樣送出。對回覆批次而言，請分別繼續每個貼文。
4. 當沒有下一頁、cursor 重複，或你自己的頁面／支出上限已達到時就停止。

分頁中繼資料反映的是最後一個上游回應；回傳的集合可能在結果上限處被截斷。即使 `has_next=false`，也不能保證所有 X 歷史或回覆都已擷取。請顯示實際回傳數量，不要把有上限的結果集標示為所有可用資料。

每個成功頁面都可能產生費用。這五個操作依回傳結果計費，而不是固定請求費。巢狀回覆與其他回傳記錄都可能影響計費數量；不要只根據頂層陣列長度估算成本。請查看[目前價格](https://openapi.felo.ai/api/v1/data/prices)與控制台中的用量。完整物件欄位請參閱 [OpenAPI schema](https://openapi.felo.ai/api/v1/data/openapi.json)。