Skip to content

Paging

API routes

Lists on /external/v1 return this envelope:

Field Meaning
list The items on this page
total The exact number of matches in offset mode. null in cursor mode.
count The number of items on this page
hasMany true when more items follow this page
nextCursor In cursor mode, what to send to get the next page. Otherwise null.
generatedAt When this page was built

These parameters work on every list:

Parameter Meaning
take Page size, 1 to 50. The default is 10.
skip How many items to skip, in offset mode
paginationMode offset (the default) or cursor
cursor The nextCursor from the page before

Offset mode

Add take to skip for each new page, and stop when hasMany is false.

Cursor mode

Send paginationMode=cursor and leave out skip. Then send each nextCursor as cursor until hasMany is false. Use this to read a long list from start to end.

curl "https://production.speakeasygo.com/external/v1/events?paginationMode=cursor&take=50" \
  -H "token: $SPEAKEASY_TOKEN"

A cursor belongs to the route, your integration and the filters you sent. Keep the same filters on every page. If we change your integration's settings, an old cursor stops working: start again without one.

Sending skip in cursor mode, or cursor in offset mode, gets a 400.

Paging does not freeze the list. Items can come and go between pages.

Order

Venues and events come back ordered by id, which is stable but not useful for display. Events are not ordered by date, so sort them yourself. Seating areas also come back by id unless you sort by price.

Venue routes

  • GET /partners/events, GET /partners/events/statistics: skip and take (up to 50), with total, count and hasMany in the answer. The default page size is 10 for events and 50 for statistics.
  • GET /partners/sync/...: no paging. You get everything since your checkpoint in one answer, which can be large. See Keep your data in sync.

Paging on orders, reservations and guests

These lists use a cursor only, with take up to 200. total is always null. A page can be short or empty while more follows, so read hasMany, and send nextCursor back with the same filters. The last page answers nextUpdatedSince, the only safe place to resume from. See Sync orders, reservations and guests.