# Pagination

When using the SQR B2B API, you may receive multiple data records, such as a list of consented digital identities.
These records are often returned in segments instead of a complete set. This process is called pagination.

Understanding pagination is important to ensure you retrieve all required data, as additional records may need to be fetched through subsequent queries.

## Walkthrough

When querying the SQR B2B API, responses that return multiple records  are paginated.
Pagination ensures that large result sets are broken down into smaller, more manageable responses.

The pagination `object`is included in the API response and provides metadata about the current page of results.
You can use this information to fetch additional records by adjusting your query parameters.

You may also include the pagination object in your initial request, defining your explicit pagination requirements.

### Pagination Object

Example pagination object.


```
{
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 150
  }
}
```

| Field | Type | Description | Default | Example |
|  --- | --- | --- | --- | --- |
| `pagination.limit` | number | Maximum number of records returned per request. Must be `>= 1`. | `100` | `10` |
| `pagination.offset` | number | Number of pages to skip before starting to return results. Must be `>= 0`. | `0` | `0` |
| `pagination.total` | number | Total number of records matching the request, across all pages. | — | `150` |


#### Usage

* `limit` controls the page size. Increase or decrease this value depending on how many records you want per response.
* `offset` determines the starting point. To fetch subsequent pages, increment this value by the limit.
* `total` allows you to calculate how many pages of data are available.


### Examples

#### Request without pagination

A request without pagination can be made, and will result in default pagination pages limits.

Request


```
{
    "filters": {...},
    "result_keys": [....]
}
```

Response


```
{
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 150
  },
  "results": [ ... 10 user records ... ]
}
```

The above example returns a 10 records per page, and a total of 150 available records.

To fetch the second page, repeat the request specifying the required offset.

#### Request with pagination

Specify a second page via an `offset` value of 1.

Request


```
{
    "filters": {...},
    "result_keys": [....],
    "pagination": {
      "offset": 1,
      "limit": 10
    }
}
```

Response


```
{
  "pagination": {
    "limit": 10,
    "offset": 1,
    "total": 150
  },
  "results": [ ... 10 user records ... ]
}
```

The second page again returns 10 records per page, in this instance commencing from the 11th record.

### Best Practices

* Use sensible limits, such as 10–100 to balance performance and bandwidth.
* Always check the total field to know if additional requests are required.
* Be mindful of rate limits; avoid unnecessary repeated calls for the same data.