# Pagination

Transact API endpoints have the capacity to return a large number of results. To ensure responses remain
performant and reasonably sized, certain endpoints return results over multiple pages, one page per call. The size of a page
is endpoint-specific.

All paginated endpoints implement a common structure for **cursor-based pagination**:

- A page is represented by an opaque cursor string.
- The `cursor` query parameter indicates which page to return (when omitted, the first page of results is returned).
- Each page of results contains cursors for neighbouring pages, to be used in your next request.
- Parameters other than `cursor` must not change between page requests.

## Receive all results

To receive all results from a paginated endpoint, you must first call the endpoint without a `cursor` parameter.
The paginated response will look something like the following:

```json title="Paginated response, first page"
{
  "items": [
    // first page of results
  ],
  "next": "<next page cursor>",
  "first": "<first page cursor>",
  "last": "<last page cursor>",
  "self": "<current page cursor>",
  "query": {}
}
```

Take the `next` cursor and call the endpoint again with `?cursor=<next page cursor>`. This will return the
second page - note the new `prev` cursor option.

```json title="Paginated response, second page"
{
  "items": [
    // second page of results
  ],
  "prev": "<previous page cursor>",
  "next": "<next page cursor>",
  "first": "<first page cursor>",
  "last": "<last page cursor>",
  "self": "<current page cursor>",
  "query": {}
}
```

Continue this process until there is no `next` cursor supplied. This is the final page of results.

```json title="Paginated response, last page"
{
  "items": [
    // last page of results
  ],
  "prev": "<previous page cursor>",
  "first": "<first page cursor>",
  "last": "<last page cursor>",
  "self": "<current page cursor>",
  "query": {}
}
```