ページネーション

API のリスト系エンドポイントはデータをページ単位で返します。プラットフォームには歴史的に2つのページネーション方式があります。どちらの方式かは インタラクティブリファレンス のエンドポイントごとに記載されています。

方式 1 — オフセットと X-Total-Count

クラシックなオフセットページネーションです。リクエストは limit（ページサイズ）と offset（スキップするレコード数）のクエリパラメータを受け取ります:

curl -H "Authorization: Bearer mbp_YOUR_TOKEN" "https://your-domain/api/bots/BOT_ID/subscribers?limit=50&offset=100"

レコードの総数はレスポンスヘッダー X-Total-Count で返されます。ページ数はこの値から計算できます。offset が X-Total-Count の値より小さい間、limit ずつ offset を増やしながらページを進めてください。レスポンスボディは現在のページの要素の配列です。

方式 2 — カーソル before と has_more

時系列で並んだフィード（例: ダイアログのメッセージ）向けのカーソルページネーションです。リクエストは limit と、省略可能なカーソル before（最後に取得した要素の識別子またはマーク）を受け取ります:

curl -H "Authorization: Bearer mbp_YOUR_TOKEN" "https://your-domain/api/bots/BOT_ID/users/USER_ID/dialog?limit=50&before=CURSOR"

レスポンスには要素のページと has_more フラグが含まれます。has_more が true の間は、最後に取得した要素のカーソルを before に指定してリクエストを繰り返してください。has_more が false になったら最後のページです。

どちらの方式を使うか

方式を選ぶのはユーザーではなく、エンドポイントが決定します。参照リスト系は通常オフセットと X-Total-Count を使用し、時系列フィードはカーソル before と has_more を使用します。常に リファレンス のエンドポイントページで確認してください。

次のステップ