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

# Pagination

> How cursor-based pagination works in the Verial API.

All list endpoints return paginated results using cursor-based pagination. This provides stable, consistent paging even when records are created or deleted between requests.

## Query Parameters

| Parameter | Type    | Default | Description                            |
| --------- | ------- | ------- | -------------------------------------- |
| `limit`   | integer | `20`    | Number of items per page (1-100)       |
| `cursor`  | string  |         | Opaque cursor from a previous response |

## Response Shape

Every list endpoint returns a `data` array and a `_meta` object:

```json theme={null}
{
  "data": [
    { "id": "env_clxyz123", "name": "Primary Care Clinic" },
    { "id": "env_clxyz456", "name": "Cardiology Practice" }
  ],
  "_meta": {
    "next": "eyJpZCI6ImVudl9jbHh5ejQ1NiJ9",
    "prev": null,
    "limit": 20
  }
}
```

| Field         | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `_meta.next`  | Cursor pointing to the next page. `null` when there are no more results. |
| `_meta.prev`  | Cursor pointing to the previous page. `null` on the first page.          |
| `_meta.limit` | The limit that was applied to this request.                              |

## Paging Forward

Pass the `next` cursor from the previous response to fetch the next page:

```bash theme={null}
# First page
curl "https://api.verial.ai/environments?limit=20" \
  -H "Authorization: Bearer vk_xxx"

# Next page
curl "https://api.verial.ai/environments?limit=20&cursor=eyJpZCI6ImVudl9jbHh5ejQ1NiJ9" \
  -H "Authorization: Bearer vk_xxx"
```

Continue until `_meta.next` is `null`.

## Paging Backward

Pass the `prev` cursor to go back one page:

```bash theme={null}
curl "https://api.verial.ai/environments?limit=20&cursor=eyJpZCI6ImVudl9jbHh5ejEyMyJ9" \
  -H "Authorization: Bearer vk_xxx"
```

## Sort Order

Results are sorted by creation date descending (newest first). This order is fixed and cannot be changed via query parameters.

## Cursor Format

Cursors are opaque strings. Do not parse, construct, or store them long-term. They encode an internal position and may change format between API versions. Always use the cursor values returned in `_meta`.

## Notes

* The maximum `limit` is **100**. Values above 100 are clamped.
* The minimum `limit` is **1**.
* An invalid or expired cursor returns a `400 Bad Request` error.