---
title: ページ送り
description: 一覧の API で、件数を指定して結果を複数のページに分けて取得する方法。
---

一覧の API は結果を複数のページに分けて返します。1回の要求で返す件数は `limit` で指定し、次のページは前の応答の `next_cursor` を `cursor` に渡して取得します。

## ページ送りに対応している API

現在、ページ送りに対応している API は次の1つです。

| API | 並び順 | 必要な権限 |
| --- | --- | --- |
| [`GET /products`](/api-reference/products/external-list-products)（商品の一覧） | 作成日時の新しい順。同じ日時のときは ID の降順 | `products:read` |

## パラメータ

クエリパラメータで指定します。

| パラメータ | 型 | 既定 | 範囲 | 説明 |
| --- | --- | --- | --- | --- |
| `limit` | 整数 | `20` | 1〜100 | 1ページに返す件数です。 |
| `cursor` | 文字列 | なし | 1,024文字まで | 前のページの応答の `next_cursor` です。最初のページでは指定しません。 |

ここに無いクエリパラメータを付けると、`400 invalid_input` が返ります。

## 応答の形

```json 応答
{
  "items": [
    { "id": "…", "name": "…" }
  ],
  "next_cursor": "…"
}
```

- `items`: このページの結果です。商品の一覧では商品のオブジェクトが入ります。
- `next_cursor`: 次のページを取得するための値です。最後のページでは `null` になります。結果が0件のときは、`items` が空の配列で、`next_cursor` は `null` です。

`next_cursor` は中身に意味を持たせていない文字列です。中身を解釈したり、自分で組み立てたりせず、受け取った値をそのまま次の要求に渡します。

## 全件を取得する手順

1. **最初のページを取得する**

    `cursor` を付けずに呼びます。件数を変えたいときは `limit` を付けます。

2. **next_cursor を確かめる**

    応答の `next_cursor` が `null` なら、最後のページです。ここで終わります。

3. **次のページを取得する**

    `next_cursor` の値を `cursor` に入れて、同じ API を呼びます。`next_cursor` が `null` になるまで繰り返します。

## 例

1ページ目を10件ずつ取得します。

```sh
curl "https://api.cozeni.net/external/v1/products?limit=10" \
  -H "Authorization: Bearer $COZENI_API_KEY"
```

応答の `next_cursor` を `cursor` に入れて、2ページ目を取得します。

```sh
curl "https://api.cozeni.net/external/v1/products?limit=10&cursor=<前の応答の next_cursor>" \
  -H "Authorization: Bearer $COZENI_API_KEY"
```

サンドボックスではベース URL を `https://api-sandbox.cozeni.net/external/v1` にし、サンドボックスの API キー（`cozeni_sk_sandbox_` で始まる）を使います。

## エラー

| HTTP | `code` | 原因 |
| --- | --- | --- |
| 400 | `invalid_input` | `cursor` の値が壊れているか、1,024文字を超えています。 |
| 400 | `invalid_input` | `limit` が1〜100の整数ではありません。 |
| 400 | `invalid_input` | 仕様に無いクエリパラメータを付けました。 |

ほかのエラーは [エラー](/api-reference/errors) を参照してください。呼び出し回数の上限は [レート制限](/api-reference/rate-limits) を参照してください。
