Pagination

Collection endpoints that can return large result sets use a consistent pagination envelope.

Response shape

{
  "meta": {
    "total": 250,
    "limit": 100,
    "offset": 0
  },
  "results": []
}

Query parameters

Where pagination is supported, partners typically pass:

Defaults and maximums are endpoint-specific and documented in OpenAPI. Do not assume every collection uses the same default page size.

Where pagination appears

Examples of paginated collections:

• Groups assigned to the caller
• Addresses in a group
• Group flex schedules and flex aggregation windows
• Device lists and many time-series / forecast result sets

Some “latest” or single-resource endpoints return one object (or a small fixed set) and are not paged.

Reliable consumption pattern

1. Request the first page with an explicit limit.
2. Advance offset by the number of items consumed (or by limit, consistently).
3. Stop when offset + results.length >= meta.total, or when an empty results array is returned.
4. Persist checkpoints for long-running sync jobs so a failure can resume.

Guidance

• Prefer smaller pages for interactive clients.
• Prefer larger but bounded pages for batch sync.
• Do not assume ordering is chronological unless the endpoint documents it.
• When combining filters (date ranges + pagination), keep the filter set identical across pages.