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.

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.

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:

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

Pagination direction

Notice that you can only move to the next page using the keyset based pagination.

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.

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:

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

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.

Random access pagination example

Here we specify both the page_size and the page parameters.

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