# カーソルベースのページネーション — next_page_token ガイド

> v1 APIのリストエンドポイントは、ページ番号ではなく、不透明なカーソルベースのページネーションを使用します。これは、next_page_token をそのまま渡して使用し、自分でデコードしたり構築したりしないでください。

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

## リストエンベロープ

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

```json
{
  "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バージョン間で安定していると想定したりしないでください。唯一の保証は、与えられたトークンを渡せば次のページが取得できるということです。

## 例：バッチのページング

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

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

```json
{
  "data": [ { "batch_name": "260716-4K9P", "status": "succeeded", "document_count": 3, "created_at": "2026-07-16T09:12:03Z" } ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
```

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

```bash
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` エラー（[エラーハンドリング](/developers/guides/errors) を参照）を返すため、破損したトークンはループを静かに再開させることなく、すぐに表面化します。

## `limit` パラメータ

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

---

Source: https://imagetotable.ai/ja/developers/guides/pagination