メインコンテンツへスキップ

​
概要

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

​
リクエストパラメータ

パラメータ型必須デフォルト値説明
limitintegerいいえ201 ページあたりの返却件数。範囲は 1-100
pagestringいいえ—前回のレスポンスの next_page が返す不透明なカーソル
before_idstringいいえ—互換カーソル: この ID より前のレコードを返す
after_idstringいいえ—互換カーソル: この 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
}

​
フィールド説明

フィールド型説明
dataarray現在のページのリソースリスト
next_pagestring | null次のページ用の不透明なカーソル。page クエリパラメータとして渡します
first_idstring | null現在のページの最初のレコードの ID
last_idstring | null現在のページの最後のレコードの ID
has_morebooleanさらにデータがあるかどうか

​
基本的な使い方

​
最初のページの取得

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

​
次のページの取得

前ページレスポンスの next_page を page として使用します。 
# 次の 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 も受け付けます。 
# 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 をトラバースします。 
#!/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.
> 100400 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_PAT"

​
空の結果

データがない、または末尾に到達した場合: 
{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}

​
注意事項

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

​
次のステップ

概要

Qoder Cloud Agents の全体像。