> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ページネーション

> Qoder Cloud Agents API のリスト型エンドポイントで使用するカーソルページングの仕様と利用方法。

## 概要

Qoder Cloud Agents API のリスト型エンドポイントは **カーソルページネーション**（Cursor-based Pagination）を採用しています。レスポンスの `next_page` の値を次のリクエストの `page` クエリパラメータとして使用します。データ変動時でもカーソルは安定しています。

## リクエストパラメータ

| パラメータ       | 型       | 必須  | デフォルト値 | 説明                                |
| ----------- | ------- | --- | ------ | --------------------------------- |
| `limit`     | integer | いいえ | 20     | 1 ページあたりの返却件数。範囲は 1-100           |
| `page`      | string  | いいえ | —      | 前回のレスポンスの `next_page` が返す不透明なカーソル |
| `before_id` | string  | いいえ | —      | 互換カーソル: この ID より前のレコードを返す         |
| `after_id`  | string  | いいえ | —      | 互換カーソル: この ID より後のレコードを返す         |

<Note>
  `page`、`before_id`、`after_id` は相互排他です。複数のカーソルを渡すと `400 invalid_request_error` が返されます。
</Note>

## レスポンス構造

すべてのリスト型エンドポイントは統一されたページングエンベロープを返します。

```json theme={null}
{
  "data": [
    { "id": "agent_abc123", "name": "my-agent", "..." : "..." },
    { "id": "agent_def456", "name": "another-agent", "..." : "..." }
  ],
  "next_page": "agent_def456",
  "first_id": "agent_abc123",
  "last_id": "agent_def456",
  "has_more": true
}
```

### フィールド説明

| フィールド       | 型              | 説明                                     |
| ----------- | -------------- | -------------------------------------- |
| `data`      | array          | 現在のページのリソースリスト                         |
| `next_page` | string \| null | 次のページ用の不透明なカーソル。`page` クエリパラメータとして渡します |
| `first_id`  | string \| null | 現在のページの最初のレコードの ID                     |
| `last_id`   | string \| null | 現在のページの最後のレコードの ID                     |
| `has_more`  | boolean        | さらにデータがあるかどうか                          |

## 基本的な使い方

### 最初のページの取得

```bash theme={null}
# 最初の 10 件の Agent を取得 \
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"
```

### 次のページの取得

前ページレスポンスの `next_page` を `page` として使用します。

```bash theme={null}
# 次の 10 件の Agent を取得 \
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10&page=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"
```

### 互換カーソル

一部のエンドポイントは、ID ベースのカーソル互換のために `before_id` と `after_id` も受け付けます。

```bash theme={null}
# agent_def456 より後の 10 件のレコードを取得 \
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 完全なトラバース例

以下のスクリプトはすべての Agent をトラバースします。

```bash theme={null}
#!/bin/bash
# すべての Agent をトラバースして名前を表示
BASE_URL="https://api.qoder.com/api/v1/cloud"
next_page=""
page_num=1

while true; do
  # URL を構築
  url="$BASE_URL/agents?limit=50"
  if [ -n "$next_page" ]; then
    url="$url&page=$next_page"
  fi

  # リクエストを発行
  response=$(curl -s "$url" \
    -H "Authorization: Bearer $QODER_PAT")

  # レスポンスを解析
  count=$(echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data']))")
  next_page=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('next_page') or '')")

  echo "${page_num} ページ目: ${count} 件のレコードを取得"

  # 現在のページのデータを処理
  echo "$response" | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
for item in data:
    print(f\"  - {item['id']}: {item.get('name', 'unnamed')}\")
"

  if [ -z "$next_page" ]; then
    break
  fi

  page_num=$((page_num + 1))

  # リクエスト間隔、過剰な速度を回避
  sleep 0.1
done

echo "トラバース完了"
```

## limit パラメータの説明

| 値       | 動作                                                                                 |
| ------- | ---------------------------------------------------------------------------------- |
| 渡さない    | デフォルトで 20 件返す                                                                      |
| 1       | 最小値、1 件返す                                                                          |
| 100     | 最大値、100 件返す                                                                        |
| 0 または負数 | 400 `invalid_request_error` を返す。メッセージは `Field 'limit' must be a positive integer.` |
| > 100   | 400 `invalid_request_error` を返す。メッセージは `limit exceeds maximum of 100`              |

<Warning>
  `limit > 100` を渡すと 400 が返されます。より大きな結果セットをページングするには `limit=100` と `page` を使用してください。
</Warning>

```bash theme={null}
# 1 件のみ取得、データ存在の確認に使用 \
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 空の結果

データがない、または末尾に到達した場合:

```json theme={null}
{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## 注意事項

1. **カーソルの安定性** — `page` カーソルは不透明であり、返された値をそのまま渡す必要があります。
2. **ソート方向** — デフォルトで作成時刻の降順（最新が先頭）。
3. **互換カーソル** — `before_id` と `after_id` は ID ベースのカーソル互換のために保持されています。
4. **並行安全性** — 複数のクライアント間で並行してページングしても安全です。

## 次のステップ

<CardGroup cols={2}>
  <Card title="概要" icon="rocket" href="/ja/cloud-agents/overview">
    Qoder Cloud Agents の全体像。
  </Card>
</CardGroup>