Pagination

How the Claret API pages through large result sets — offset and cursor pagination.

All list endpoints paginate their results. The API uses two pagination styles depending on the kind of data:

Style	Used by	Why
Offset (page numbers)	Reference and master data (items, uoms, calendars, locations, etc.)	These sets are small and benefit from random page access and a total count.
Cursor	Transactional data (sales, inventory, supply plans, financial plans)	These sets are large; cursors page efficiently without an expensive COUNT(*).

Pagination details appear under meta.pagination in every list response.

Looking for the old current_index / next_index style? That belonged to the legacy endpoints. See Migrating from Legacy Endpoints.

Offset pagination (reference data)

Control the page with two query parameters:

Parameter	Default	Description
page	1	The page number to retrieve.
per_page	25	Records per page. Each endpoint has a maximum (commonly 100, up to 1000 for larger reference sets).

Request:

curl "https://plan.claret.app/{tenant}/api/v1/items?page=2&per_page=50" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Response meta.pagination:

{
  "meta": {
    "pagination": {
      "result_count": 50,
      "current_page": 2,
      "per_page": 50,
      "total": 1234,
      "last_page": 25
    }
  }
}

To walk every page, increment page until current_page equals last_page.

Cursor pagination (transactional data)

Large datasets use an opaque cursor instead of page numbers:

Parameter	Default	Description
cursor	(none)	The cursor token for the next page. Omit on the first request.
per_page	100	Records per page. Maximum 5000.

First request (no cursor):

curl "https://plan.claret.app/{tenant}/api/v1/inventory?per_page=500" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Response meta.pagination:

{
  "meta": {
    "pagination": {
      "result_count": 500,
      "per_page": 500,
      "has_more": true,
      "next_cursor": "eyJpZCI6MTUwMCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ",
      "prev_cursor": null
    }
  }
}

Next request — pass next_cursor back as cursor:

curl "https://plan.claret.app/{tenant}/api/v1/inventory?per_page=500&cursor=eyJpZCI6MTUwMCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Keep following next_cursor until has_more is false. At that point next_cursor is null and you have read the entire set.

Cursor responses intentionally omit total and last_page. Counting every matching row on a large transactional table is expensive, so the API reports only whether more pages exist.

Looping in pseudocode

cursor = null
repeat:
    response = GET /inventory?per_page=500 (+ &cursor=<cursor> if set)
    process(response.data)
    cursor = response.meta.pagination.next_cursor
until response.meta.pagination.has_more == false

Choosing per_page

Larger pages mean fewer requests but heavier responses. Each request also spends credits and a rate-limit token, so for bulk reads prefer larger pages (up to each endpoint's maximum) over many small ones.

Related documentation

• Filtering & Sorting — narrow and order results before paging.

• Rate Limiting — why fewer, larger pages are friendlier.

• The API Reference — the per_page maximum for each endpoint.