# Paginating search results

**Learn how to manage large result sets using pagination. Pagination helps you organise search results into smaller, more manageable pages, improving performance and user experience.**

## How pagination works

The Demand API uses different pagination mechanisms depending on the endpoint:

| Pagination mechanism | Endpoints |
|  --- | --- |
| Token-based pagination using `next_page`. | * Search endpoints ([accommodations](/demand/docs/open-api/demand-api/accommodations/accommodations/search)) and ([cars](/demand/docs/open-api/demand-api/cars/search))
* [Location endpoints](/demand/docs/open-api/demand-api/commonlocations)
* [Orders details](/demand/docs/open-api/demand-api/orders/orders/details)

 |
| Timestamp-based incremental pagination. | * [accommodations/details/changes](/demand/docs/open-api/demand-api/accommodations/accommodations/details/changes)

 |


## Token-based pagination for search endpoints

With this pagination mechanism you can:

✅ Specify how many results to return per page using `maximum_results` (cars) or `rows` (accommodation).

✅ Retrieve additional pages using the `next_page` token provided in the response.

Note
The value of `rows` and `maximum_results` must be a multiple of 10.

### Requesting additional pages with next_page

When your search response contains more results than can fit on a single page, the API includes a `next_page` token.
This token contains encoded information from your original request.

Important
The `next_page` token expires 3 hours after it is generated. Make sure to use it within that time.

To request the next page:

1. Copy the value from the `next_page` field in the response.
2. Include it as the `page` parameter in your next request.


#### Example - Search response with next_page token:


```json
{
  "data": [ ... ],
  "metadata": {
    "next_page": "eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im...fQ.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A",
    "total_results": 122
  }
}
```

#### Example - Requesting the next page


```json
{ "page":"eyJhbGciOiJIUzI1NiJ9.eyJwIjp7Im1heGltdW1fcmVzdWx0cyI6MTAsIm9mZnNldCI6MTB9LCJhdWQiOiJDQVJTX1NVUFBMSUVSUyIsImV4cCI6MTY4MzY0NzMwNX0.y7NmH48mm7lImd2WxsHdotj6n-dVQAzJCGCnIJCKy3A"
}
```

You do not need to resend other parameters such as dates or locations — the token automatically inherits them from your original request.

If the `next_page` field is missing from the response, there are no additional results.

## Timestamp-based pagination for accommodation changes

The [/accommodations/details/changes endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/details/changes) uses timestamp-based pagination to help you retrieve updates incrementally.

### How it works

1. You send a request with a `last_change` timestamp in ISO 8601 format (UTC only).
Example:



```json
{
  "last_change": "2025-06-22T12:00:00+00:00",
  "filters": {
    "countries": ["nl"]
  }
}
```

1. The response may include a `next` timestamp — this represents the next point in time from which to continue fetching updates.


Example — Response with next timestamp:


```json
{
  "data": {
    "changes": {
      "changed": [403115, ...],
      "closed": [9876832, ...],
      "opened": [8034270, ...]
    },
    "from": "2025-06-22T12:00:00+00:00",
    "next": "2025-06-22T12:24:42+00:00",
    "total_changes": 5125
  }
}
```

1. To retrieve the next batch of changes, you make a new request using the value of `next` as your new `last_change` parameter.


Example — Requesting the next batch of changes:


```json
{
  "last_change": "2025-06-22T12:24:42+00:00",
  "filters": {
    "countries": ["nl"]
  }
}
```

If no changes are returned

* The next field is omitted.
* You should repeat the call after one minute with the same `last_change` timestamp to check for new updates.


### Important notes

* The endpoint returns up to around 5000 accommodation IDs per request. The actual number may vary due to grouping of result by second.
* You should continue requesting with the updated next timestamp until no further next field is returned, meaning you've retrieved all available changes.
* You keep requesting changes in chronological order by advancing the last_change timestamp based on the next value provided in the response.


## Limiting results per page

You can control how many results are returned per page:

| Endpoint | Parameter | Default value | Notes |
|  --- | --- | --- | --- |
| Accommodation | `rows` | 100 | Must be a multiple of 10. |
| Cars | `maximum_results` | 100 | Must be a multiple of 10. |


### Accommodation example - Using rows

Return up to 30 properties per page:


```json
{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2025-09-12",
  "checkout": "2025-09-14",
  "city": -2612321,
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "rows": 30
}
```

The value of `rows` must be a multiple of 10.

### Cars example - Using maximum_results

Return up to 50 car rental results per page:


```json
{
    "booker": {
      "country": "nl"
    },
    "currency": "EUR",
    "driver": {
      "age": 36
    },
    "route": {
      "dropoff": {
        "datetime": "2025-05-08T11:05:00",
        "location": {
          "coordinates": {
            "latitude": 52.309456,
            "longitude": 4.762266
          }
        }
      },
      "pickup": {
        "datetime": "2025-05-20T11:05:00",
        "location": {
          "coordinates": {
            "latitude": 52.309456,
            "longitude": 4.762266
          }
        }
      },
      "maximum_results": 50
    }
  }'
```

### Full pagination example - Accommodation search

Let’s say you want to display 50 accommodations per page in your application. Here’s how pagination would work:

**Step 1** - Initial request (50 results per page)


```json
{
  "booker": {
    "country": "gb",
    "platform": "desktop"
  },
  "checkin": "2025-09-12",
  "checkout": "2025-09-14",
  "city": -2612321,
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  },
  "rows": 50
}
```

**Step 2** -  Response includes a `next_page` token:


```json
{
  "products": [ ... ],
  "next_page": "eyJhbGciOi..."
}
```

**Step 3** - Request next page

- Copy the "next_page" token and include it as `page` in the next request to retrieve the next pages:



```json
{
  "page": "eyJhbGciOi..."
}
```

Repeat step 3 until the `next_page` token is no longer included in the response.

## Best practices

✓ Always check for a `next_page` token in the response to determine if more results are available.

✓ Use `maximum_results` or `rows` to control page size and optimise performance.

✓ Combine pagination with filters and sorting to build efficient, user-friendly search experiences.

✓ Be mindful of the 3-hour token expiry window.

✓ For /accommodations/details/changes, always update your `last_change` parameter based on the `next` timestamp to ensure you do not miss updates.

- Learn how to use filters when [searching for accommodation](/demand/docs/accommodations/filter-sorting) and [car rentals](/demand/docs/cars/cars-filter-sorting).
- Refer to the [Accommodation search use cases guide](/demand/docs/accommodations/search-examples) for more practical examples.
- Explore how to [search for car rentals](/demand/docs/cars/cars-quick-guide#step-1---search-for-available-vehicles) to avoid errors in requests.