ガイド

ページネーション

v1のすべてのリストエンドポイント（GET /batches、 GET /account/usage、および将来のリストエンドポイント）は、同じ方法でページネーションされます。ページ番号ではなくカーソルを使用します。

リストエンベロープ

すべてのリストレスポンスには、同じ3つのトップレベルフィールドがあります。

{
  "data": [ /* ... */ ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
  • data — このページの結果の配列。
  • has_more — このページの後に別のページが存在するかどうか。
  • next_page_token — 次のリクエストで ?page_token= としてこれを渡すと、次のページを取得できます。has_more が false の場合は常に null になります。この2つのフィールドが矛盾することはありません。

カーソルを使用する理由（ページ番号ではない理由）

v1には ?page=2 スタイルのページネーションや offset パラメータはありません。バッチや使用履歴などのリストは常に変化しています。新しいバッチが完了したり、新しい使用行が書き込まれたりするため、オフセットベースの「2ページ目」では、リクエストの間に何かが挿入されると、行が静かにスキップされたり重複したりする可能性があります。カーソルはそれを回避します。各トークンは、変動する数値オフセットではなく、基になる順序の正確な位置を指します。

トークンは不透明です

next_page_token はページ番号ではなく、その内部エンコーディングは契約の一部ではありません。厳密に不透明な文字列として扱ってください。受け取ったものをそのまま渡し、デコードしたり、自分で構築したり、その形式がAPIバージョン間で安定していると想定したりしないでください。唯一の保証は、与えられたトークンを渡せば次のページが取得できるということです。

例：バッチのページング

最初のリクエスト、まだトークンはありません：

curl "https://imagetotable.ai/api/v1/batches?limit=20" \
  -H "Authorization: Bearer $API_KEY"
{
  "data": [ { "batch_name": "260716-4K9P", "status": "succeeded", "document_count": 3, "created_at": "2026-07-16T09:12:03Z" } ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}

次のリクエスト、前のレスポンスのトークンを使用：

curl "https://imagetotable.ai/api/v1/batches?limit=20&page_token=eyJpZCI6IDQyfQ" \
  -H "Authorization: Bearer $API_KEY"

各レスポンスの next_page_token を使って、has_more が false を返すまで繰り返します。不正な形式のトークンや期限切れのトークンは、最初のページを静かに返すのではなく、invalid_parameter エラー（エラーハンドリング を参照）を返すため、破損したトークンはループを静かに再開させることなく、すぐに表面化します。

limit パラメータ

すべてのリストエンドポイントは、ページサイズを制御するためのオプションの limit クエリパラメータを受け入れます。各エンドポイントには独自のデフォルト値と最大値があります（正確な範囲は APIリファレンス の各エンドポイントのページを参照してください）。許可された範囲外の limit をリクエストすると、invalid_parameter が返されます。

📮 contact email: [email protected]