---
title: Pagination
description: How list endpoints return pages of records with limit and offset
group: Guides
---

# Pagination

# Pagination

When an endpoint returns many records, the response is a page rather than the full set. Paginated responses include an `items` array plus paging fields so you can walk through every row.

## How it works

Pass `limit` and `offset` as query parameters:

| Parameter | Default | Range | Meaning |
| --- | --- | --- | --- |
| `limit` | `50` | `1`–`200` | How many records to return in this request |
| `offset` | `0` | `0` or greater | How many records to skip from the start of the result set |

The response body always includes:

```json
{
  "items": [],
  "total": 0,
  "limit": 50,
  "offset": 0
}
```

- `items` — the records for this page
- `total` — how many records match the query across all pages
- `limit` / `offset` — the values applied to this response (echoed from the request, after defaults and clamping)

Some list routes also accept `search` (and similar filters). Filtering changes which rows match; pagination still applies to that filtered set. See each endpoint for the exact query parameters.

## Walking every page

1. Call the list endpoint with your filters. Start with `offset=0` (or omit it).
2. Read `items` and `total` from the response.
3. If `offset + limit < total`, request the same path again with `offset` increased by `limit`.
4. Stop when `offset + limit >= total`, or when `items` is empty.

Example first page:

```http
GET /api/v1/workspaces/acme/certificates?limit=50&offset=0
```

```json
{
  "items": [{ "id": "…", "name": "Python Fundamentals" }],
  "total": 120,
  "limit": 50,
  "offset": 0
}
```

Next page:

```http
GET /api/v1/workspaces/acme/certificates?limit=50&offset=50
```

Keep advancing `offset` by `50` until you have covered `total` (here `120`).

## Which endpoints paginate

List endpoints that return collections use this shape, including:

- [List certificates](/docs/api/certificates/list)
- [List issues](/docs/api/issues/list)
- [List recipients](/docs/api/issues/list-recipients)

Single-resource endpoints (for example get a certificate, or public verify) return one object and do not paginate.

Verifycate does not use cursor tokens (`cursor`, `next`, `prev`) on these routes. Always page with `limit` and `offset`.