# Pagination

Some collections might return very large amounts of items.
This will usually be the case with `/v1/bookings` or `/v1/events` endpoints.
To work with these collections we require pagination which will allow you to page through the collection at your own rate.

## Using cursor and limit

Collections support the `cursor` and `limit` query paramters which allow you to page through a collecttion.

- `cursor`: An opaque string indicating that there are more pages to read
- `limit`: An integer indicating the size of each page.


Whenever you query a collection you will receive a JSON object containing the items along with a `next` field which will contain the cursor for the next page if any.

If the `next` field is empty, you have reached the end of the collection.
This could be because there are fewer items than the limit in the collection or if you have already paged to the end.

If the `next` field has a value you should repeat the call to the endpoint to get the next page, setting the `cursor` query parameter to the value of `next`.


```sh
$ curl http://api.understory.io/v1/bookings
{
 "next": "<cursor for the next page>",
 "items": [
    {...},
    {...}
 ]
}
```

Below is an example of how you could page through all bookings with a Javascript `while` loop.

Paging through bookings
let next;
let bookings = [];

while (next) {
  const response = await fetch(
    `https://api.understory.io/v1/bookings?limit=100&cursor=${next}`,
    {
      headers: {
        authorization: `Bearer ${process.env.TOKEN}`,
        'user-agent': 'Understory API Demo',
      },
    }
  );

  if (response.status !== 200) {
    throw new Error(
      `Failed to fetch bookings: ${response.status} ${response.statusText}`
    );
  }

  bookings.push(response.items);

  next = response.next;
}

console.log(`Fetched ${bookings.length} bookings:`, bookings);