# Pagination of API lists

API endpoints returning lists of resources usually support pagination, for example [List all monitors](https://betterstack.com/docs/uptime/api/list-all-existing-monitors/).

## Query parameters

Control pagination with following query parameters:

| Parameter  | Type    | Value                                                                                                          |
|------------|---------|----------------------------------------------------------------------------------------------------------------|
| `per_page` | Integer | Number of resources per page. The default value is `50` and maximum value is `250` if not specified otherwise. |
| `page`     | Integer | The page number you want to return. Starts with `1`.                                                           |

See the `pagination` object in the API list response body to find other pages:

| Parameter          | Type             | Values                                                                                    |                                                                      
|--------------------|------------------|-------------------------------------------------------------------------------------------|
| `pagination.first` | String           | The URL of the first page of results.                                                     |
| `pagination.last`  | String           | The URL of the last page of results.                                                      |
| `pagination.prev`  | String or `null` | The URL of the previous page of results. Is `null` when viewing the first page. |
| `pagination.next`  | String or `null` | The URL of the next page of results. Is `null` when viewing the last page.      |

## Examples

```shell
[label Example cURL to list monitors]
curl --request GET \
  --url "https://uptime.betterstack.com/api/v2/monitors?per_page=20&page=3" \
  --header "Authorization: Bearer $TOKEN"
```

```json
[label Example response body listing monitors]
{
  "data": [
    {
      "id": "41",
      "type": "monitor",
      "attributes": {
        monitor's attributes omitted...
      }
    },
    {
      "id": "42",
      "type": "monitor",
      "attributes": {
        monitor's attributes omitted...
      }
    }
  ],
  "pagination": {
    "first": "https://uptime.betterstack.com/api/v2/monitors?per_page=20&page=1",
    "last": "https://uptime.betterstack.com/api/v2/monitors?per_page=20&page=3",
    "prev": "https://uptime.betterstack.com/api/v2/monitors?per_page=20&page=2",
    "next": null
  }
}
```