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

# Pagination

> How to paginate through large result sets

## Overview

List endpoints in the HopNow API use **page-based pagination** to handle large result sets efficiently.

## Parameters

All list endpoints support these query parameters:

| Parameter | Type    | Default | Description                      |
| --------- | ------- | ------- | -------------------------------- |
| `page`    | integer | 1       | Page number (starts from 1)      |
| `size`    | integer | 10      | Number of items per page (1-100) |

## Example Request

```bash theme={null}
GET /v1/customers/{customer_id}/accounts?page=2&size=20
```

## Response Format

Paginated responses include metadata about the result set:

```json theme={null}
{
  "items": [
    {
      "id": "acct_1234567890abcdef",
      "name": "Account 1",
      "status": "active",
      "created": "2024-01-01T00:00:00Z"
    },
    {
      "id": "acct_fedcba0987654321",
      "name": "Account 2",
      "status": "active",
      "created": "2024-01-02T00:00:00Z"
    }
  ],
  "total": 150,
  "page": 2,
  "size": 20,
  "pages": 8
}
```

### Response Fields

| Field   | Type    | Description                           |
| ------- | ------- | ------------------------------------- |
| `items` | array   | Array of objects for the current page |
| `total` | integer | Total number of items                 |
| `page`  | integer | Current page number                   |
| `size`  | integer | Number of items per page              |
| `pages` | integer | Total number of pages                 |

## Pagination Examples

### First Page

```bash theme={null}
GET /v1/customers/{customer_id}/accounts?page=1&size=25
```

### Next Page

```bash theme={null}
GET /v1/customers/{customer_id}/accounts?page=2&size=25
```

### Last Page

```bash theme={null}
# If pages = 8
GET /v1/customers/{customer_id}/accounts?page=8&size=25
```

## Code Examples

<CodeGroup>
  ```python Python theme={null}
  def get_all_accounts(client, customer_id):
      accounts = []
      page = 1

      while True:
          response = client.get(
              f"/v1/customers/{customer_id}/accounts",
              params={"page": page, "size": 100}
          )
          data = response.json()

          accounts.extend(data["items"])

          if page >= data["pages"]:
              break

          page += 1

      return accounts
  ```

  ```javascript JavaScript theme={null}
  async function getAllAccounts(client, customerId) {
      const accounts = [];
      let page = 1;

      while (true) {
          const response = await client.get(
              `/v1/customers/${customerId}/accounts`,
              { params: { page, size: 100 } }
          );
          const data = response.data;

          accounts.push(...data.items);

          if (page >= data.pages) {
              break;
          }

          page++;
      }

      return accounts;
  }
  ```
</CodeGroup>

## Best Practices

### Choose Appropriate Page Sizes

* **Interactive UI**: 10-25 items per page
* **Bulk processing**: 50-100 items per page
* **Maximum allowed**: 100 items per page

### Handle Empty Results

```python theme={null}
response = client.get("/v1/customers/{customer_id}/accounts")
data = response.json()

if not data["items"]:
    print("No accounts found")
else:
    print(f"Found {len(data['items'])} accounts on this page")
```

### Monitor Total Count

The `total` count helps track collection changes:

```python theme={null}
first_response = client.get("/v1/accounts", params={"page": 1})
initial_total = first_response.json()["total"]

# After processing...
last_response = client.get("/v1/accounts", params={"page": 1})
final_total = last_response.json()["total"]

if final_total != initial_total:
    print(f"Collection size changed: {initial_total} → {final_total}")
```