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

# Pagination

> Learn how to paginate through API responses

The API uses cursor-based pagination to efficiently handle large datasets for endpoints that return multiple items. Cursor pagination provides better performance than offset-based pagination, especially for large datasets.

## Query Parameters

| Parameter      | Type    | Default | Description                                        |
| -------------- | ------- | ------- | -------------------------------------------------- |
| `page[size]`   | integer | 30      | Number of items per page (max 100)                 |
| `page[cursor]` | string  | -       | Cursor token for retrieving the next/previous page |

## Response Format

Paginated responses follow the JSON:API specification and include three main sections:

```json theme={null}
{
    "data": [
        // Array of resource items
    ],
    "meta": {
        "path": "https://api.aspect.systems/v1/examples",
        "per_page": 30,
        "next_cursor": "eyJpZCI6MTUwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
        "prev_cursor": null
    },
    "links": {
        "first": "https://api.aspect.systems/v1/examples?page%5Bsize%5D=30",
        "prev": null,
        "next": "https://api.aspect.systems/v1/examples?page%5Bcursor%5D=eyJpZCI6MTUwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9&page%5Bsize%5D=30"
    }
}
```

## Usage Examples

**First page (default size):**

```bash theme={null}
GET /v1/examples
```

**First page with custom size:**

```bash theme={null}
GET /v1/examples?page[size]=50
```

**Next page using cursor:**

```bash theme={null}
GET /v1/examples?page[cursor]=eyJpZCI6MTUwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9&page[size]=30
```

## Navigation

To navigate through paginated results:

1. **First page**: Make a request without the `page[cursor]` parameter
2. **Subsequent pages**: Use the `next_cursor` value from the `meta` section, or use the `next` URL from the `links` section
3. **Previous pages**: Use the `prev_cursor` value from the `meta` section, or use the `prev` URL from the `links` section

**Recommended approach**: Use the URLs provided in the `links` section for navigation, as they include all necessary parameters and proper encoding.