---
title: Pagination | Luminary
---

The Luminary API uses cursor-based pagination for all list endpoints. This approach provides consistent, reliable pagination even when data is being added or removed between requests.

## Parameters

All paginated endpoints accept the following optional query parameters:

| Parameter | Type    | Description                                                       | Default |
| --------- | ------- | ----------------------------------------------------------------- | ------- |
| `limit`   | integer | Maximum number of items to return (1-1000)                        | 50      |
| `after`   | string  | Cursor for forward pagination. Returns items after this cursor.   | —       |
| `before`  | string  | Cursor for backward pagination. Returns items before this cursor. | —       |

Example:

Terminal window

```
curl -X GET "https://your-subdomain.withluminary.com/api/public/v1/households?limit=25&after=eyJpZCI6Imhv..." -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Response Structure

Every paginated response includes:

```
{
  "data": [...],
  "page_info": {
    "has_next_page": true,
    "has_previous_page": true,
    "start_cursor": "eyJpZCI6Imhv...",
    "end_cursor": "eyJpZCI6Imhv..."
  },
  "total_count": 150
}
```

| Field               | Type    | Description                                           |
| ------------------- | ------- | ----------------------------------------------------- |
| `has_next_page`     | boolean | Indicates if more items exist after the current page  |
| `has_previous_page` | boolean | Indicates if more items exist before the current page |
| `start_cursor`      | string  | Cursor pointing to the first item in the current page |
| `end_cursor`        | string  | Cursor pointing to the last item in the current page  |

## Navigating Forward Through Results

To paginate forward through a list:

1. Make an initial request without any cursor
2. Check if `has_next_page` is `true`
3. Use the `end_cursor` value as the `after` parameter in your next request
4. Repeat until `has_next_page` is `false`