# Pagination

Every list returns one page at a time, with a `pagination` object that says where you are:

```json
{
  "success": true,
  "data": [/* ... */],
  "pagination": { "total": 412, "page": 1, "page_size": 50, "total_pages": 9 }
}
```

Two query parameters pick the page:

| Parameter   | Default | Notes                                                              |
| ----------- | ------- | ------------------------------------------------------------------ |
| `page`      | `1`     | Pages start at `1` and go up to `1000000`.                         |
| `page_size` | `50`    | Up to `100`. A larger value is treated as `100`, not refused.      |

A `page` outside that range, or a `page` or `page_size` that is not a whole number, returns `400`
`VALIDATION_ERROR` naming the parameter.

<CodeTabs syncKey="lang">

```bash title="curl"
curl "https://api.mos.getbrokerplus.ca/v1/contacts?page=2&page_size=100" \
  -H "Authorization: Bearer $BROKERPLUS_API_KEY"
```

```ts title="TypeScript"
const res = await fetch("https://api.mos.getbrokerplus.ca/v1/contacts?page=2&page_size=100", {
  headers: { Authorization: `Bearer ${process.env.BROKERPLUS_API_KEY}` },
});
const { data, pagination } = await res.json();
```

```python title="Python"
import os

import requests

res = requests.get(
    "https://api.mos.getbrokerplus.ca/v1/contacts",
    params={"page": 2, "page_size": 100},
    headers={"Authorization": f"Bearer {os.environ['BROKERPLUS_API_KEY']}"},
)
body = res.json()
data, pagination = body["data"], body["pagination"]
```

</CodeTabs>

Page numbers are for looking at a list. **To keep a copy of a list up to date, don't page through it
again and again.** Use `updated_since` with `after_id`, or the change feed, as
[Staying in sync](/sync) explains. A row that changes while you page moves, and page numbers then
skip it.

The change feed (`GET /v1/changes`) pages with a checkpoint instead of a page number. Its
`pagination` holds `next_checkpoint` and `has_more`.

## The order of a list

The main record lists (contacts, leads, deals, submissions, intakes, and tasks) come newest first,
by when they were created. With `updated_since`, every list switches to oldest change first. The
other lists follow the order BrokerPlus shows:

| List                              | Order                                 |
| --------------------------------- | ------------------------------------- |
| Appointments                      | By start time, earliest first.        |
| Pipelines, tags, meeting types    | The order the broker set.             |
| Task notes                        | Pinned first, then newest first.      |
| Teams                             | Oldest first.                         |
| Team members                      | By role, then by start date.          |
| Lenders                           | By name.                              |
| Opportunities                     | Most recently changed first.          |
| Communications, users, consents   | Newest first.                         |

Don't rely on a position in a list to find a record. Read it by `id`.