Skip to main content
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

ParameterDescriptionDefaultMax
itemsPerPageNumber of items per page201000
pagePage number1-

​
Example

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

​
Response

{
  "@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:
FieldDescription
hydra:firstLink to the first page
hydra:previousLink to the previous page (if available)
hydra:nextLink to the next page (if available)
hydra:lastLink 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: 
curl -i 'https://api.syntage.com/taxpayers/{taxpayerId}/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.