# Pagination

Requests that return multiple items may support pagination. The API supports two modes of pagination, **random access pagination** and **keyset pagination**. By default the API will use the keyset pagination unless you explicitly set the `page` query parameter which will enable the random access pagination.

{% hint style="info" %}

### Which one to use?

This depends on your use case. If you know that the result set is small and you must access a random page (out of order) then the random access pagination is the one you should select.

In any other case the keyset pagination, which is also the default one, is suggested.
{% endhint %}

## Keyset pagination

The keyset pagination mode, which is the default one, expects the user to provide the next cursor for navigating to the next page. The cursor value is included in the `pagination` object of the response.

The response `pagination` object is of the form:

```json
{
  "pagination": {
    "next": "g3QAAAABaAJkAAtwcmVkaWN0aW9uc2QAB3VzZXJfaWRtAAAABzEwMDI2NzE=",
    "page_size": 1000
  }
}
```

{% hint style="info" %}

### Pagination direction

Notice that you can only move to the next page using the keyset based pagination.
{% endhint %}

{% hint style="info" %}

### Common use case

The most common use case for keyset based pagination is to get all the data from a large dataset. You constantly hit the endpoint till the `next` cursor value is `null`.
{% endhint %}

## Random access pagination

Random access pagination (offset based) is the simplest one. You need to specify the `page` parameter which corresponds to the page to get data from.

In case of random access pagination the `pagination` response object will be of the form:

```json
{
  "pagination": {
    "page": 2,
    "page_count": 78946,
    "page_size": 10,
    "total_count": 789458
  }
}
```

{% hint style="warning" %}

### Performance issues

Random access pagination is not suggested for large datasets. There will be performance issues for large page numbers and you may get error responses.
{% endhint %}

{% hint style="info" %}

### Random access pagination example

Here we specify both the `page_size` and the `page` parameters.

```bash
$ curl --request GET \\
  --url 'http://api.vaix.ai/api/crm/predictions/retention?page_size=5&page=12' \\
  --header "Content-Type: application/json"
```

{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportradar.com/personalization/overview/using-the-api/pagination.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.