> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 分页

> Qoder Cloud Agents API 列表接口的游标分页规范与遍历示例。

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 之后的记录          |

<Note>`page`、`before_id` 和 `after_id` 不能同时使用。同时传入多个 cursor 将返回 400 `invalid_request_error`。</Note>

## 响应结构

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

```json theme={null}
{
  "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        | 是否还有更多数据                       |

## 基本用法

### 获取第一页

```bash theme={null}
# 获取前 10 个 Agents
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"
```

### 获取下一页

使用上一页响应中的 `next_page` 作为 `page`：

```bash theme={null}
# 获取下一页 10 个 Agents
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10&page=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"
```

### 兼容游标

部分接口也接受 `before_id` 和 `after_id` 作为基于 ID 的兼容游标：

```bash theme={null}
# 获取 agent_def456 之后的 10 条记录
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"
```

## 完整遍历示例

以下脚本遍历所有 Agents：

```bash theme={null}
#!/bin/bash
# 遍历所有 Agents 并打印名称
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} 条记录"

  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`              |

<Warning>
  传入 `limit > 100` 会返回 400。需要更多数据时，请使用 `limit=100` 并通过 `page` 翻页。
</Warning>

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

## 空结果

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

```json theme={null}
{
  "data": [],
  "next_page": null,
  "first_id": null,
  "last_id": null,
  "has_more": false
}
```

## 注意事项

1. **游标稳定性** — `page` 是不透明游标，应按响应原样传回
2. **排序方向** — 默认按创建时间降序（最新在前）
3. **兼容游标** — `before_id` 和 `after_id` 作为基于 ID 的兼容游标保留
4. **并发安全** — 可安全地在多个客户端间并行分页

## 下一步

<CardGroup cols={2}>
  <Card title="概览" icon="rocket" href="/zh/cloud-agents/overview">
    了解 Qoder Cloud Agents 的整体架构。
  </Card>
</CardGroup>