分页-Qoder CN 系列(Lingma)-阿里云帮助中心

Qoder Cloud Agents API 的列表接口采用游标分页（Cursor-based Pagination）。通过 before_id 和 after_id 参数定位数据窗口，确保在数据变动时分页结果的稳定性。

请求参数

参数	类型	必需	默认值	说明
`limit`	integer	否	20	每页返回数量，范围 1-100
`before_id`	string	否	—	返回此 ID 之前的记录（向前翻页）
`after_id`	string	否	—	返回此 ID 之后的记录（向后翻页）

before_id 和 after_id 不能同时使用。同时传入将返回 400 invalid_request_error。

部分资源（Files、Skills、Vaults）的列表端点使用 after/before 作为参数名，与本页定义的 after_id/before_id 等价，服务端均可识别。

响应结构

所有列表接口返回统一的分页信封：

{
  "data": [
    { "id": "agent_abc123", "name": "my-agent", "...": "..." },
    { "id": "agent_def456", "name": "another-agent", "...": "..." }
  ],
  "first_id": "agent_abc123",
  "last_id": "agent_def456",
  "has_more": true
}

字段说明

字段	类型	说明
`data`	array	当前页的资源列表
`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"

向后翻页

使用上一页响应中的 last_id 作为 after_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"

向前翻页

使用当前页的 first_id 作为 before_id：

# 获取 agent_abc123 之前的 10 条记录
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&before_id=agent_abc123" \
  -H "Authorization: Bearer $QODER_PAT"

完整遍历示例

以下脚本遍历所有 Agents：

#!/bin/bash
# 遍历所有 Agents 并打印名称
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
has_more=true
after_id=""
page=1

while [ "$has_more" = "true" ]; do
  # 构造 URL
  url="$BASE_URL/agents?limit=50"
  if [ -n "$after_id" ]; then
    url="$url&after_id=$after_id"
  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']))")
  has_more=$(echo "$response" | python3 -c "import sys,json; print(str(json.load(sys.stdin)['has_more']).lower())")
  after_id=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin)['last_id'] or '')")

  echo "第 ${page} 页：获取 ${count} 条记录"

  page=$((page + 1))

  # 请求间隔，避免过快
  sleep 0.1
done

echo "遍历完成"

limit 参数说明

值	行为
不传	默认返回 20 条
1	最小值，返回 1 条
100	最大值，返回 100 条
0 或负数	返回 400 错误
> 100	静默截断为 100 条（HTTP 200，不报错），`has_more` 反映剩余数据是否存在

传入 limit > 100 时 API 不会返回 400，而是静默截断到 100 条。如果你的代码假设传 limit=500 就能拿到 500 条，实际只会拿到前 100 条且没有任何错误提示。需要更多数据时，请使用 after_id 翻页。

# 仅获取 1 条，用于检查是否存在数据
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"

空结果

当没有数据或已到达末尾时：

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

注意事项

游标稳定性 — 游标基于资源 ID，即使期间有新数据写入也不会导致重复或遗漏
排序方向 — 默认按创建时间降序（最新在前）
已删除资源 — 已删除的资源 ID 用作游标时可能返回 400 错误
并发安全 — 可安全地在多个客户端间并行分页