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

# Pagination

Collection endpoints return paginated results with navigation links and metadata. The API supports two pagination styles:

* **Offset-based pagination** (default) - Navigate using page numbers
* **Cursor-based pagination** - Navigate using cursor tokens for large datasets

## Offset-based Pagination

The default pagination style. Use page numbers to navigate through results.

### Query Parameters

| Parameter      | Description              | Default | Max  |
| -------------- | ------------------------ | ------- | ---- |
| `itemsPerPage` | Number of items per page | 20      | 1000 |
| `page`         | Page number              | 1       | -    |

### Example

```bash theme={null}
curl -i 'https://api.syntage.com/events?page=2&itemsPerPage=50' \
  --header 'Accept: application/ld+json' \
  --header 'X-Api-Key: {apiKey}'
```

### Response

```json theme={null}
{
  "@context": "/contexts/Event",
  "@id": "/events",
  "@type": "hydra:Collection",
  "hydra:totalItems": 150,
  "hydra:member": [
    // ... items on this page
  ],
  "hydra:view": {
    "@id": "/events?page=2",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/events?page=1",
    "hydra:previous": "/events?page=1",
    "hydra:next": "/events?page=3",
    "hydra:last": "/events?page=3"
  }
}
```

The `hydra:view` object contains links to navigate the collection:

| Field            | Description                              |
| ---------------- | ---------------------------------------- |
| `hydra:first`    | Link to the first page                   |
| `hydra:previous` | Link to the previous page (if available) |
| `hydra:next`     | Link to the next page (if available)     |
| `hydra:last`     | Link to the last page                    |

### Considerations

* **Best for smaller datasets** - Works well for collections with moderate size
* **Page drift** - If items are added or removed while paginating, you may see duplicates or miss items
* **Performance** - For large datasets, consider cursor-based pagination

## Cursor-based Pagination

Uses opaque cursor tokens instead of page numbers. More efficient for large datasets and provides stable results even when items change during pagination.

### Benefits

* **Better performance** - More efficient database queries for large datasets
* **Stable results** - No duplicates or missed items when data changes during pagination
* **Scalable** - Performance doesn't degrade as you paginate deeper into the collection

### Example

Add the `X-Pagination-Style: cursor` header to enable cursor pagination:

```bash theme={null}
curl -i 'https://api.syntage.com/entities/{entityId}/invoices?itemsPerPage=10' \
  --header 'Accept: application/ld+json' \
  --header 'X-Api-Key: {apiKey}' \
  --header 'X-Pagination-Style: cursor'
```

The response includes `hydra:next` and `hydra:previous` URIs with the cursor token embedded. To fetch the next page, make a GET request to the `hydra:next` URI.

### Considerations

* **No total count by default** - The `hydra:totalItems` field is omitted to improve performance. To include it, add the `X-Pagination-Enable-Partial: 0` header (this may impact response times for large datasets).
* **Availability** - Cursor pagination is available on most collection endpoints.