Pagination
Page size, limit caps, and when to use appointment cursor pagination instead of offsets.
Environment tip: All examples use
v3.onsched.comfor production. Replace the host withapi-stage.onsched.comwhen calling the staging environment.
Purpose
List endpoints return a page of rows plus enough metadata to request the next page. Limits are validated. Asking for more than the cap returns 400, it does not silently shrink the page.
Defaults and caps
| Collection | Default limit | Max limit | Overflow | Notes |
|---|---|---|---|---|
| Customers | 20 | 100 | 400 | GET /v3/customers |
| Appointments (page) | 20 | 100 | 400 | GET /v3/appointments. Offset (page - 1) * limit must not exceed 10,000 (400 if it would). |
| Appointments (cursor) | 20 | 100 | 400 | GET /v3/appointments/cursor. Preferred for exports. |
| Locations, services, resources | 20 | 500 | 400 | Dashboard pickers need a higher cap. |
page starts at 1.
Customers example
curl "https://v3.onsched.com/v3/customers?limit=100&page=1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"Stop when data is shorter than limit, or empty.
Appointments
For UI pages that need a total count, use GET /v3/appointments with limit and page. For exports and backend ingestion, use Cursor Pagination for Appointments:
- First request sends filters,
sort,order, andlimit. - Later requests send only
cursor. - On
429, honorRetry-Afterand retry the same page or cursor.
Errors
Over-max limit is a validation 400 (message: "Validation Error", errors[].path is limit). Appointment offset over 10,000 is also 400.
See also
Updated 1 day ago