X データ

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

すべての例は 概要 の FELO_API_KEY を使用します。呼び出しには プラットフォーム残高 が使われ、Felo Pro クレジットは使われません。レスポンス例は説明用であり、実際の内容や任意フィールドは変動します。

操作を選ぶ

1. ユーザープロフィールを取得する

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

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 が含まれ、プロフィール文、フォロワー数、認証情報、その他のメタデータも含まれる場合があります。バッチで返されるプロフィール数は要求数より少なくなる場合があります。配列位置ではなく、ユーザー名または ID で一致させてください。

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

2. ユーザーを検索する

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

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 パラメーターはありません。

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

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

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

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 操作とそこで返されるカーソルを使用してください。返信にトップレベル投稿のカーソルを再利用しないでください。

4. 投稿を検索する

POST /api/v1/data/x/tweet/search

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 のターゲットでは上流の 1 ページを読み取り、それより大きいターゲットでは最大 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
}

5. 返信を読み取る

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

プレースホルダーを実際の投稿 ID に置き換えてください:

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 の下にグループ化されます。各エントリには独自のページ分割状態があります:

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

リクエストごとの返信上限

各リクエストは tweet_id ごとに 1 つの上流返信ページを読み取り、最大 100 件の返信を保持します。すべての返信ページを自動取得するわけではありません。最大 20 個の ID のバッチでは、100 件の上限は各 results エントリに個別に適用されます。実際の件数はこれより少ない場合があります。

各エントリの total は、そのエントリで返された返信数であり、投稿の完全な返信数ではありません。続行するには、そのエントリの next_cursor を使用し、次のリクエストにはその 1 件の投稿 ID のみを送信してください。1 リクエストあたりの上限を増やす limit パラメーターはありません。

ページ分割とコスト制御

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

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

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

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