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 错误
- 并发安全 — 可安全地在多个客户端间并行分页
