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

# Pagination

> How pagination and sorting work in the Sunset API.

# Pagination

All list endpoints return paginated results. The Sunset API supports both **page-based** and **cursor-based** pagination.

## Page-Based Pagination

The default pagination method. Use query parameters to control the page, page size, and sort order.

### Query Parameters

| Parameter    | Type    | Default | Description                                                |
| ------------ | ------- | ------- | ---------------------------------------------------------- |
| `page`       | integer | `1`     | Page number (1-indexed).                                   |
| `per_page`   | integer | `25`    | Items per page (max 100).                                  |
| `sort_by`    | string  | varies  | Field to sort by. Available values depend on the endpoint. |
| `sort_order` | string  | `desc`  | Sort direction: `asc` or `desc`.                           |

### Example Request

````bash theme={null}
curl "https://api.example.com/v1/cases?page=2&per_page=10&sort_by=created_at&sort_order=asc"```

### Response Metadata

Every paginated response includes a `meta` object:

```json
{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 10,
    "total_count": 47,
    "total_pages": 5,
    "next_cursor": null,
    "has_more": true
  }
}
````

| Field         | Description                                                                           |
| ------------- | ------------------------------------------------------------------------------------- |
| `page`        | Current page number.                                                                  |
| `per_page`    | Items per page for this request.                                                      |
| `total_count` | Total number of items across all pages.                                               |
| `total_pages` | Total number of pages.                                                                |
| `next_cursor` | Cursor for the next page (null when using page-based pagination or on the last page). |
| `has_more`    | Whether more results exist beyond this page.                                          |

## Cursor-Based Pagination

For high-volume resources (transactions, balance history, phone calls), cursor-based pagination is recommended. It provides consistent results even when new records are added between requests.

### How It Works

1. Make your first request without a cursor:

````bash theme={null}
curl "https://api.example.com/v1/cases/{case_id}/bank-accounts/{account_id}/transactions?per_page=50"```

2. The response includes a `next_cursor` in the `meta` object:
```json
{
  "data": [...],
  "meta": {
    "per_page": 50,
    "next_cursor": "eyJpZCI6IjAxSzVXRjA2...",
    "has_more": true
  }
}
````

3. Use the `cursor` parameter for subsequent requests:

````bash theme={null}
curl "https://api.example.com/v1/cases/{case_id}/bank-accounts/{account_id}/transactions?per_page=50&cursor=eyJpZCI6IjAxSzVXRjA2..."```

4. Continue until `has_more` is `false`.

<Note>
When using cursor-based pagination, the `page` parameter is ignored. The `total_count` and `total_pages` fields may not be available.
</Note>

## Iterating Through All Pages

### Page-Based (Python)

```python
import requests

headers = {}
page = 1
all_cases = []

while True:
    response = requests.get(
        f"https://api.example.com/v1/cases?page={page}&per_page=100",
        headers=headers
    )
    data = response.json()
    all_cases.extend(data["data"])

    if page >= data["meta"]["total_pages"]:
        break
    page += 1
````

### Cursor-Based (Python)

```python theme={null}
import requests

headers = {}
cursor = None
all_transactions = []

while True:
    params = {"per_page": 100}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        f"https://api.example.com/v1/cases/CASE_ID/bank-accounts/ACCOUNT_ID/transactions",
        headers=headers,
        params=params
    )
    data = response.json()
    all_transactions.extend(data["data"])

    if not data["meta"]["has_more"]:
        break
    cursor = data["meta"]["next_cursor"]
```

## Filtering

Many list endpoints support additional query parameters for filtering. Check each endpoint's documentation for available filters. Filters can be combined:

````bash theme={null}
# List open bank accounts at Chase, sorted by balance
curl "https://api.example.com/v1/cases/{case_id}/bank-accounts?status=open&institution_name=Chase&sort_by=current_balance&sort_order=desc"```
````