ページネーション

概要

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 より後のレコードを返す

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

レスポンス構造

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

{
  "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	さらにデータがあるかどうか

基本的な使い方

最初のページの取得

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

次のページの取得

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

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

互換カーソル

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

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

完全なトラバース例

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

#!/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_ACCESS_TOKEN")

  # レスポンスを解析
  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`

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

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

空の結果

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

{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}

注意事項

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

次のステップ

概要

Qoder Cloud Agents の全体像。

​概要

​リクエストパラメータ

​レスポンス構造

​フィールド説明

​基本的な使い方

​最初のページの取得

​次のページの取得

​互換カーソル

​完全なトラバース例

​limit パラメータの説明

​空の結果

​注意事項

​次のステップ

概要

概要

リクエストパラメータ

レスポンス構造

フィールド説明

基本的な使い方

最初のページの取得

次のページの取得

互換カーソル

完全なトラバース例

limit パラメータの説明

空の結果

注意事項

次のステップ