> ## 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.

# Pagination

> How cursor-based pagination works across the Devin API

All list endpoints in the Organization and Enterprise APIs use **cursor-based pagination**. This provides consistent, efficient pagination regardless of the size of the result set.

## How it works

Every list endpoint accepts two query parameters:

| Parameter | Type    | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| `first`   | integer | Maximum number of items to return per page (default varies by endpoint) |
| `after`   | string  | Opaque cursor from a previous response. Omit for the first page         |

### Response format

List responses include pagination metadata:

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

| Field           | Description                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------- |
| `items`         | Array of results for the current page                                                           |
| `has_next_page` | `true` if there are more results                                                                |
| `end_cursor`    | Pass this as the `after` parameter to get the next page. `null` when `has_next_page` is `false` |
| `total`         | Total number of matching items (may be omitted by some endpoints for performance)               |

## Example: Paginating through sessions

### First page

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

### Next page

Use the `end_cursor` value from the previous response:

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

### Collecting all results

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

## Migrating from offset-based pagination

If you're migrating from API v1 or v2, replace `offset`/`limit` with `after`/`first`:

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

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

Cursor-based pagination is more reliable than offset-based pagination because it isn't affected by items being added or removed between pages.