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

# 分页

> Devin API 中基于游标的分页工作原理

Organization API 和 Enterprise API 中的所有列表端点都使用 **基于游标的分页**。这可以在结果集大小无论如何变化的情况下，仍然提供一致且高效的分页体验。

<div id="how-it-works">
  ## 工作原理
</div>

每个列表接口都接受两个查询参数：

| Parameter | Type    | Description               |
| --------- | ------- | ------------------------- |
| `first`   | integer | 每页返回的最大项目数（默认值因接口而异）      |
| `after`   | string  | 上一个响应返回的不透明游标。获取第一页时省略该参数 |

<div id="response-format">
  ### 响应格式
</div>

列表类型的响应包含分页元数据：

```json theme={null}
{
  "items": [...],
  "has_next_page": true,
  "end_cursor": "eyJsYXN0X2lkIjoiYWJjMTIzIn0=",
  "total": 142
}
```

| 字段              | 说明                                                             |
| --------------- | -------------------------------------------------------------- |
| `items`         | 当前页的结果数组                                                       |
| `has_next_page` | 如果还有更多结果，则为 `true`                                             |
| `end_cursor`    | 将此作为 `after` 参数传入，以获取下一页。当 `has_next_page` 为 `false` 时为 `null` |
| `total`         | 匹配项的总数（出于性能原因，某些端点可能会省略该字段）                                    |

<div id="example-paginating-through-sessions">
  ## 示例：对会话进行分页
</div>

<div id="first-page">
  ### 第一页
</div>

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=10" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="next-page">
  ### 下一页
</div>

使用上一个响应中的 `end_cursor` 值：

```bash theme={null}
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=10&after=eyJsYXN0X2lkIjoiYWJjMTIzIn0=" \
  -H "Authorization: Bearer $DEVIN_API_KEY"
```

<div id="collecting-all-results">
  ### 汇总所有结果
</div>

```python theme={null}
import os
import requests

org_id = os.environ["DEVIN_ORG_ID"]
url = f"https://api.devin.ai/v3/organizations/{org_id}/sessions"
headers = {"Authorization": f"Bearer {os.environ['DEVIN_API_KEY']}"}
all_sessions = []
cursor = None

while True:
    params = {"first": 50}
    if cursor:
        params["after"] = cursor

    response = requests.get(url, headers=headers, params=params).json()
    all_sessions.extend(response["items"])

    if not response.get("has_next_page"):
        break
    cursor = response["end_cursor"]

print(f"Fetched {len(all_sessions)} sessions")
```

<div id="migrating-from-offset-based-pagination">
  ## 从基于偏移量的分页迁移
</div>

如果你正在从 API v1 或 v2 迁移，请将 `offset`/`limit` 替换为 `after`/`first`：

```bash theme={null}
# 之前 (v1/v2)
curl ".../v1/sessions?offset=50&limit=25"

# 之后
curl ".../v3/organizations/{org_id}/sessions?first=25&after=CURSOR_FROM_PREVIOUS_PAGE"
```

基于游标的分页比基于偏移量的分页更可靠，因为它不会受到页面之间新增或删除条目的影响。