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

# Pagination

> How to navigate paginated list endpoints

All list endpoints return paginated results. You control pagination using query parameters, and the response includes metadata to help you navigate through pages.

## Query Parameters

| Parameter  | Type    | Default | Description                        |
| ---------- | ------- | ------- | ---------------------------------- |
| `page`     | integer | `1`     | Page number (1-indexed)            |
| `pageSize` | integer | `100`   | Number of items per page (max 100) |

### Example

```bash theme={null}
# Get page 2
curl -X GET "https://api.maxcare.ai/v3/patients?page=2" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"
```

## Response Format

Every paginated response includes a `pagination` object alongside the data:

```json theme={null}
{
  "code": "success",
  "data": {
    "patients": [
      {
        "id": "pat_c56103bcd39c46d39f3138dd2b5e05f6",
        "mrn": "MM0000000005",
        "firstName": "Max",
        "lastName": "Test",
        "gender": "Male",
        "dateOfBirth": "1989-09-06"
      },
      {
        "id": "pat_8de030393a9e417ab2b3a8b8df183631",
        "mrn": null,
        "firstName": "EZDerm Other",
        "lastName": "Test",
        "gender": null,
        "dateOfBirth": null
      }
    ],
    "pagination": {
      "page": 2,
      "pageSize": 100,
      "totalCount": 1503,
      "totalPages": 16
    }
  }
}
```

### Pagination Fields

| Field        | Type   | Description                            |
| ------------ | ------ | -------------------------------------- |
| `page`       | number | Current page number                    |
| `pageSize`   | number | Number of items per page               |
| `totalCount` | number | Total number of items across all pages |
| `totalPages` | number | Total number of pages                  |

## Iterating Through All Pages

To fetch all records, loop until `page` equals `totalPages`:

<CodeGroup>
  ```javascript Node.js theme={null}
  async function fetchAllPatients(apiKey, orgId) {
    const patients = [];
    let page = 1;
    let totalPages = 1;

    while (page <= totalPages) {
      const response = await fetch(
        `https://api.maxcare.ai/v3/patients?page=${page}&pageSize=100`,
        {
          headers: {
            "Authorization": `Bearer ${apiKey}`,
            "X-Organization-Id": orgId,
          },
        }
      );
      const json = await response.json();

      patients.push(...json.data.patients);
      totalPages = json.data.pagination.totalPages;
      page++;
    }

    return patients;
  }
  ```

  ```python Python theme={null}
  import requests

  def fetch_all_patients(api_key: str, org_id: str) -> list:
      patients = []
      page = 1
      total_pages = 1

      while page <= total_pages:
          response = requests.get(
              "https://api.maxcare.ai/v3/patients",
              params={"page": page, "pageSize": 100},
              headers={
                  "Authorization": f"Bearer {api_key}",
                  "X-Organization-Id": org_id,
              },
          )
          data = response.json()

          patients.extend(data["data"]["patients"])
          total_pages = data["data"]["pagination"]["totalPages"]
          page += 1

      return patients
  ```
</CodeGroup>

## Tips

* Use the **largest `pageSize`** that makes sense for your use case (max 100) to minimize the number of requests.
* The first page is `page=1`, not `page=0`.
* An empty page returns an empty array with `totalCount: 0`.
* Some list endpoints support **search filters** (e.g., `?search=smith` on `/v3/patients`). Pagination applies after filtering.