> ## Documentation Index
> Fetch the complete documentation index at: https://developer.maatstays.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page numbers, has_more, and deliberately no total.

List endpoints page with two query parameters and answer with two fields:

```bash theme={null}
curl "https://maatstays.wtf/v1/blocks?page=2&page_size=100" \
  -H "Authorization: Bearer $MAAT_PARTNER_TOKEN"
```

```json theme={null}
{
    "items": [],
    "has_more": false
}
```

| Parameter   | Default | Bounds  | Meaning              |
| :---------- | :------ | :------ | :------------------- |
| `page`      | `1`     | ≥ 1     | 1-based page number. |
| `page_size` | `50`    | 1 – 200 | Rows per page.       |

Keep asking for the next `page` while `has_more` is `true`. That is the entire loop:

```python theme={null}
# Sketch: `token` comes from the exchange in the Authentication guide.
page = 1
while True:
    res = requests.get(
        "https://maatstays.wtf/v1/blocks",
        headers={"Authorization": f"Bearer {token}"},
        params={"page": page, "page_size": 200},
        timeout=30,
    )
    res.raise_for_status()
    body = res.json()
    for block in body["items"]:
        reconcile(block)
    if not body["has_more"]:
        break
    page += 1
```

## There is no total, on purpose

The response tells you whether another page exists, not how many rows exist. Counting
the whole set to answer one page is work neither side needs — and for a reconciliation
read, "walk until `has_more` is false" is the correct loop anyway. If you need a count,
count as you walk.

## Narrowing before paging

Where an endpoint offers filters — `from`/`to` on `GET /v1/blocks` bound the result to
blocks holding a night inside the window — prefer narrowing over walking the whole set.
A block whose `check_out` equals `from` holds no night in the window (departure day is
exclusive) and is not returned. Each page is bounded by the same filters, so the
`has_more` loop composes with them unchanged.