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

# How does pagination work in the Blend API?

> Paginated list endpoints return a flat JSON array and put the pagination metadata in response headers — X-Total-Count, X-Page, X-Page-Size, X-Total-Pages, and X-Remaining-Count. Page size defaults to 25 and maxes at 200.

Blend's list endpoints return a **flat JSON array**, not a wrapped object. Pagination metadata lives in the response headers instead of the body, so you read `X-Total-Count` and friends rather than looking for a `total` key. Control the window with the `page` and `page_size` query parameters; `page_size` defaults to 25 and is capped at 200.

## Read the headers

```bash theme={null}
curl -i "https://api.byblend.com/api/v1/orders?page=2&page_size=50" \
  -H "Authorization: Bearer {access_token}"
```

```http theme={null}
HTTP/1.1 200 OK
X-Total-Count: 438
X-Page: 2
X-Page-Size: 50
X-Total-Pages: 9
X-Remaining-Count: 338
Content-Type: application/json

[ { "id": "0227d1e5-...", "order_number": "ORD250312003548IAU4", ... } ]
```

| Header              | Meaning                                |
| ------------------- | -------------------------------------- |
| `X-Total-Count`     | Total items available across all pages |
| `X-Page`            | The page you just received             |
| `X-Page-Size`       | Items per page                         |
| `X-Total-Pages`     | Total pages available                  |
| `X-Remaining-Count` | Items left after this page             |

## Loop until you've drained it

`X-Remaining-Count` is the cleanest stopping condition — keep requesting until it reaches `0`.

```python theme={null}
page = 1
while True:
    r = requests.get(
        "https://api.byblend.com/api/v1/orders",
        params={"page": page, "page_size": 200},
        headers={"Authorization": f"Bearer {token}"},
    )
    yield from r.json()
    if int(r.headers["X-Remaining-Count"]) == 0:
        break
    page += 1
```

<Tip>
  Combine pagination with filters rather than paging through everything. `GET /orders?status=picked,verified` and `GET /orders?has_unmatched_prescriptions=true` will nearly always be faster than draining the full list and filtering client-side.
</Tip>

<Note>
  Requesting a `page_size` above 200 does not error — it is clamped to 200. Trust `X-Page-Size` in the response over the value you asked for.
</Note>

<CardGroup cols={3}>
  <Card title="Get orders" icon="prescription-bottle" href="/api-reference/orders/get-orders">
    Paginated, filterable by status
  </Card>

  <Card title="Get patients" icon="user" href="/api-reference/patients/get-patients">
    Paginated
  </Card>

  <Card title="Get prescriptions" icon="prescription" href="/api-reference/prescriptions/get-prescriptions">
    Paginated, filterable
  </Card>
</CardGroup>