Skip to main content

​
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

ParameterTypeDefaultDescription
pageinteger1Page number (1-indexed).
per_pageinteger25Items per page (max 100).
sort_bystringvariesField to sort by. Available values depend on the endpoint.
sort_orderstringdescSort direction: asc or desc.

​
Example Request

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
  }
}
FieldDescription
pageCurrent page number.
per_pageItems per page for this request.
total_countTotal number of items across all pages.
total_pagesTotal number of pages.
next_cursorCursor for the next page (null when using page-based pagination or on the last page).
has_moreWhether 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:
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
  }
}
  1. Use the cursor parameter for subsequent requests:
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)

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: 
# 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"```