All list endpoints support pagination to help manage large datasets. Use pagination parameters to control the number of results and navigate through pages.

​
Overview

The Intermezzo API uses cursor-based pagination for list endpoints to efficiently handle large result sets. Pagination parameters are passed as query parameters in your requests.

​
Pagination Parameters

ParameterTypeDefaultDescription
pageinteger1Page number (minimum: 1)
sizeinteger10Items per page (range: 1-100)
sort_bystringnullField to sort results by
sort_orderstring”asc”Sort order: “asc” or “desc”

The maximum page size is 100 items. Requests with size greater than 100 will return an error.

​
Making Paginated Requests

curl -X GET "https://api.intermezzo.ai/v1/resources?page=1&size=20" \
  -H "Authorization: Bearer <token>"

​
Response Structure

All paginated responses include two main sections:

​
items

An array containing the actual data for the current page.

​
meta

Pagination metadata containing:

  • total: Total number of items across all pages
  • page: Current page number
  • size: Number of items per page
  • pages: Total number of pages
  • has_next: Boolean indicating if there’s a next page
  • has_prev: Boolean indicating if there’s a previous page

​
Advanced Filtering

You can combine pagination with search and filtering capabilities:

curl -X GET "https://api.intermezzo.ai/v1/resources?page=1&size=10&search=query&search_fields=name,description" \
  -H "Authorization: Bearer <token>"

​
Best Practices

  • Start with smaller page sizes (10-25) and increase as needed
  • Always check has_next before requesting the next page
  • Use sorting to ensure consistent pagination results
  • Cache pagination metadata to reduce API calls

​
Error Handling

The API will return appropriate errors for invalid pagination parameters:

Invalid Page Size
{
  "error": "validation_error",
  "message": "size must be between 1 and 100",
  "details": {
    "field": "size",
    "value": 150
  }
}
Invalid Sort Order
{
  "error": "validation_error",
  "message": "sort_order must be 'asc' or 'desc'",
  "details": {
    "field": "sort_order",
    "value": "invalid"
  }
}