Pagination and Windows
Page through lists with cursors, query date windows, and use repeatable filters.
Cursors
Every list endpoint returns one page at a time:
limitsets the page size: 100 by default, at most 500.pagination.nextCursorin the answer points to the next page. Send it ascursorto get that page. It isnullon the last page.- Keep every other parameter the same while you page. A cursor works only with the filters it was
issued for. With other filters, or if the cursor was altered, the API answers
400 invalid_cursor: start again without a cursor.
Lists come in an order that stays the same while you page. Most lists name it (bookings, for
example, by date); visits don't, so sort them by date or startsAt yourself. You can't choose
another order, and there is no total count.
Date windows
Bookings, presence days, presence counts and visits cover a window of days:
startDateandendDateare required, asYYYY-MM-DD. Both days are included.- A window covers at most 31 days. For a longer period, send one request per window.
- A booking's
dateis the day as booked. Presence days and presence counts use days in your organization's time zone, andmeta.timeZonein their answer names it. - A visit is included when its stay overlaps the window, in the visit's own dates. Its
dateis the day it was entered for (for a calendar visit, the date ofstartsAtintimeZone), and a visit with no end, or with an end at or before its start, counts as one day.
Filters
- Most filters take one value, for example
groupIdorofficeId. userIdon bookings and presence days,hostIdandstatuson visits, andstatuson users, take several values. Repeat the parameter for each one:?userId=<id1>&userId=<id2>. A list joined by commas is refused. A filter takes at most 50 values.- An unknown parameter is refused with
400 invalid_request, so a typo never drops a filter silently.
Last updated on