---
updatedAt: 2025-12-17T13:12:51.000Z
agentTools:
  projectIndex: https://developer.candis.io/llms.txt
---

# How to use Pagination

This section describes how to use pagination when retrieving large collections of resources from the Candis API.

## Pagination Parameters

When making requests to endpoints that return collections (such as `/invoices`, `/documents`, `/reimbursement-items`, etc.), you can control the number of results using the following parameters:

* `limit`: The maximum number of items to return per request (defaults to 50 if not specified)
* `offset`: The number of items to skip before starting to collect results

> 📘 Note
>
> The maximum allowed value for the limit is 50. Setting a higher value will result in the API defaulting back to 50.

## Implementing Pagination Correctly

To retrieve all resources in a paginated manner, maintain a consistent `limit` value while incrementing the `offset` parameter for each subsequent request.

### Example

1. **First Page (Items 1-50)**
   ```shell
   curl --request GET \
        --url 'https://api.candis.io/v1/organizations/{organizationId}/invoices?offset=0&limit=50' \
        --header 'Authorization: Bearer {access_token}' \
        --header 'accept: application/json'
   ```
2. **Second Page (Items 51-100)**
   ```shell Shell
   curl --request GET \
        --url 'https://api.candis.io/v1/organizations/{organizationId}/invoices?offset=50&limit=50' \
        --header 'Authorization: Bearer {access_token}' \
        --header 'accept: application/json'
   ```
3. **Third Page (Items 101-150)**
   ```shell
   curl --request GET \
        --url 'https://api.candis.io/v1/organizations/{organizationId}/invoices?offset=100&limit=50' \
        --header 'Authorization: Bearer {access_token}' \
        --header 'accept: application/json'
   ```

<br />

## Best Practices

1. Consistent Limit Values: Always use the same `limit` value throughout your pagination sequence to ensure consistent page sizes.