> This page is for Self-Hosted, version v3.0 (default).
> For other versions, use one of these documentation indexes:
> - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt
> - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt
> - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt
> - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server.

# Pagination

Several List endpoints in the NVIDIA Run:ai control plane API return large collections. To retrieve results in smaller chunks, use offset/limit pagination.

## How Pagination Works

### Request Parameters

When an endpoint supports pagination, it typically exposes:

* `limit` - Maximum number of items to return (default 50, range 1..500)
* `offset` - The offset of the first item returned in the collection

Example (workloads): `GET /api/v1/workloads?offset=0&limit=50`

### Pagination Response

List responses may include a `next` field, alongside the collection itself (for example, `workloads`).

Example response shape (workloads):

```json
{
  "next": 1,
  "workloads": [ ... ]
}
```

Use `next` as the pointer for retrieving the next "page" of results. If `next` is not returned (or is empty), you've reached the end of the collection.

### Example: Paginate Through Workloads

#### Fetch the first page

```bash
curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "https://<COMPANY-URL>/api/v1/workloads?offset=0&limit=50"
```

The endpoint supports `offset` and `limit`.

#### Fetch the next page

Take the `next` value from the response and use it in the next request (as the next offset/page pointer).

### Combine Pagination with Sorting and Filtering

The workloads list endpoint also supports:

* **Sorting** - `sortBy` and `sortOrder`
* **Structured filtering** - `filterBy` with operators like `==`, `!=`, `>=`, `=@` (contains), etc.
* **Free-text search** - `search`

Example:

```bash
curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "https://<COMPANY-URL>/api/v1/workloads?limit=100&offset=0&sortBy=createdAt&sortOrder=desc&filterBy=allocatedGPU>=2"
```