Qoder CN 系列：分頁

Qoder Cloud Agents API 的列表介面採用 遊標分頁（Cursor-based Pagination）。預設使用上一頁響應中的 next_page 作為下一次請求的 page 參數。遊標在資料變動時仍保持穩定。

請求參數

參數	類型	必需	預設值	說明
limit	integer	否	20	每頁返回數量，範圍 1-100
page	string	否	—	上一次響應 next_page 返回的不透明遊標
before_id	string	否	—	相容遊標：返回此 ID 之前的記錄
after_id	string	否	—	相容遊標：返回此 ID 之後的記錄

響應結構

所有列表介面返回統一的分頁信封：

{
  "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 個 Agents
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

擷取下一頁

使用上一頁響應中的 next_page 作為 page：

# 擷取下一頁 10 個 Agents
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&page=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

相容遊標

部分介面也接受 before_id 和 after_id 作為基於 ID 的相容遊標：

# 擷取 agent_def456 之後的 10 條記錄
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

完整遍曆樣本

以下指令碼遍曆所有 Agents：

#!/bin/bash
# 遍曆所有 Agents 並列印名稱
BASE_URL="https://api.qoder.com.cn/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} 條記錄"

  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

# 僅擷取 1 條，用於檢查是否存在資料
curl -s "https://api.qoder.com.cn/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. 並發安全 — 可安全地在多個用戶端間並行分頁