# Felo X ユーザー投稿

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

必要なデータに応じて操作を選択してください。5 つのエンドポイントはすべて POST を使用し、共通の `data` ラッパーなしで JSON をルートに返します。

すべての例は [概要](https://openapi.felo.ai/ja/docs/data-api/guides/felo-overview.md) の `FELO_API_KEY` を使用します。呼び出しには **プラットフォーム残高** が使われ、Felo Pro クレジットは使われません。レスポンス例は説明用であり、実際の内容や任意フィールドは変動します。





## 3. ユーザーのタイムラインを取得する

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

| フィールド | 型 | 必須 | 意味 |
|---|---|---|---|
| `username` | string | いずれか 1 つの識別子が必須 | ユーザーハンドル、最大 100 文字 |
| `x_user_id` | string | いずれか 1 つの識別子が必須 | ユーザー 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 のターゲットでは上流の 1 ページを読み取り、それより大きいターゲットでは最大 50 ページまで自動で取得します。各ページの前に経過時間を確認し、60 秒を超えた時点でそれ以降のページ取得を停止します。この確認は、HTTP リクエスト全体が 60 秒以内に完了することを保証するものではありません。

取得は、目標件数に達した場合、上流に次のページがない場合、ページが空の場合、またはカーソルがない場合にも停止します。そのため、成功レスポンスに `limit` より少ない投稿しか含まれないことがあります。利用可能な場合は `has_next` と `next_cursor` を使って続行してください。

`include_replies=true` の場合、返された各投稿に最大 5 ページ分、合計最大 100 件のネストされた返信が追加されます。次のページがない、ページが空、またはカーソルを進められない場合は、より早く停止することがあります。これらのネストされた返信はトップレベルの `limit` と `total` の外にありますが、課金対象結果に含まれる場合があります。

ネストされた `replies` は完全な返信アーカイブではなく、この追加取得に対する別の継続カーソルも公開されません。返信を独立してページ分割するには、Read replies 操作とそこで返されるカーソルを使用してください。返信にトップレベル投稿のカーソルを再利用しないでください。



## ページ分割とコスト制御

`total` は、現在のレスポンス内の対応する配列の件数を数えます。投稿クエリではトップレベル投稿、返信クエリでは各結果エントリ内の返信です。これは、グローバルな一致件数、投稿の完全な返信数、または最終的な課金対象件数ではありません。

1. 最初のリクエストは `cursor` なしで送信します。
2. レスポンスから `has_next` と `next_cursor` を読み取ります。返信については、各結果エントリで読み取ります。
3. さらにページがあり、カーソルが空でない場合は、同じクエリでそのまま送信します。返信のバッチでは、各投稿を個別に続行します。
4. 次のページがない場合、カーソルが繰り返される場合、または自分のページ数や支出上限に達した場合は停止します。

ページ分割のメタデータは最後の上流レスポンスを反映しており、返されたコレクションは結果上限で切り詰められる場合があります。`has_next=false` であっても、すべての X の履歴や返信を取得したことを保証するものではありません。利用可能なデータがすべてであるかのように、制限付きの結果セットを表示しないでください。

成功した各ページには課金が発生する場合があります。これら 5 つの操作は、フラットなリクエスト शुल्कではなく返された結果に基づいて課金されます。ネストされた返信やその他の返されたレコードは課金対象件数に影響する場合があります。トップレベル配列の長さだけでコストを見積もらないでください。[現在の価格](https://openapi.felo.ai/api/v1/data/prices) とコンソールでの使用状況を確認してください。完全なオブジェクトフィールドは [OpenAPI スキーマ](https://openapi.felo.ai/api/v1/data/openapi.json) にあります。