Skip to main content

Pagination

Pagination is a technique for splitting large result sets into smaller chunks or pages. With pagination, you can retrieve only a small portion of the results at a time, which can improve performance and reduce the amount of data transmitted over the network.

Token-based pagination​

Token-based pagination works by providing two query parameters:

limit​

The limit parameter specifies the maximum number of results that should be returned in a single page. The default value is 1000.

continuationToken​

The continuationToken parameter specifies the position in the result set and is used to select which page of results to return. If omitted, the first page of the results is returned. You can include the continuationToken from the previous response to retrieve the next page of results.

Example​

For example, you can retrieve all users on pages listing 10 results as follows.

First make a request to https://$instanceId.id.nevis.cloud/nevis/api/v1/users?limit=10.

This request returns the first page of results with a maximum of 10 users. The response includes the _pagination wrapper object, which contains the continuationToken and limit.

{
    "items": [
        {
            // User 1
        },
      
      ...
      
        {
            // User 10
        }
    ],
    "_pagination": {
        "continuationToken": "1639467743000_a721ec6d-dcbf-4bcf-ac15-8ba7bba4135b",
        "limit": 10 
    }
}

To retrieve the next page of results make another request to the API and include the continuationToken in the query string: https://$instanceId.id.nevis.cloud/nevis/api/v1/users?limit=10&continuationToken=1639467743000_a721ec6d-dcbf-4bcf-ac15-8ba7bba4135b.

This request returns the next page of results, starting from the position represented by the continuationToken.

Once the continuationToken in the response is empty, all users have been retrieved.

Offset-based pagination​

Offset-based pagination works by providing two query parameters:

limit​

The limit parameter specifies the maximum number of results that should be returned in a single page. The default value is 50.

offset​

The offset parameter specifies the number of results to skip before starting to return results. The default value is 1.

note

Offset-based pagination is only supported to Query log events.

Example​

For example, you can retrieve all users on pages listing 10 results as follows.

First make a request to https://$instanceId.id.nevis.cloud/nevis/api/v1/events?limit=10&offset=1. This request returns the first page of results, with a maximum of 10 events.

To retrieve the next page of results make another request to the API and increase the value of the offset by the value of the limit in the query string: https://$instanceId.id.nevis.cloud/nevis/api/v1/events?limit=10&offset=11. This request will return the second page of results, starting from the 11th result.

Once the number of returned results is smaller than the limit, all events have been retrieved.