Skip to content

Pagination

Every /v1 list returns one page at a time and a cursor for the next one. You walk a list by sending each page’s next_cursor back as cursor, with every other parameter unchanged:

Terminal window
curl -s -G https://api.in1.getbeekon.com/v1/devices \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "limit=2"
# {"devices":[{…},{…}],"next_cursor":"dc1_AAYs…"} send cursor=dc1_AAYs… for the next page

A loop that walks a whole list is in A complete walk.

ParameterRule
limitAn integer from 1 to 500. Default 100. A value outside the range, or one that is not an integer, is 400 limit must be an integer in [1, 500] — it is never silently clamped. limit= (empty) counts as absent. You may change limit between pages of one walk.
cursorThe opaque next_cursor from the previous page. Absent or empty (cursor=) means “from the start”.

Send each parameter at most once. On every list except GET /v1/events, a defined parameter sent twice is a 400 (the server never quietly takes the first or the last), and an empty value for any defined parameter other than limit and cursor is a 400 too.

ListItems memberFiltersOrderCursor prefix
GET /v1/devicesdevicesuser_idinstall_id, byte orderdc1_
GET /v1/usersusersnoneuser_id, byte orderus1_
GET /v1/users/{user_id}/devicesdevicesthe userinstall_id, byte orderdc1_
GET /v1/locationslocationswindow and filtersrecorded_at, then idlc1_
GET /v1/locations/feedlocationsinclude_gatedarrivallf1_
GET /v1/tripstripsinstall_id, from, tostarted_at, then idtr1_
GET /v1/trips/{trip_id}/pointspointsthe triprecorded_at, then idtr1_
GET /v1/geofencesgeofencesnoneidgf1_
GET /v1/webhookswebhooksnonecreated_at, then idwh1_
GET /v1/eventseventsnonelog orderec1_
{"devices":[…],"next_cursor":"dc1_AAYs…"}
  • The items array is always present, and is [] when there is nothing to return.
  • next_cursor is always present. It is a string while more items exist, and null when the walk is complete.
  • next_cursor is decided by whether another item exists, not by whether the page is full: a list of exactly limit items completes in one page. Always loop on next_cursor, not on the item count.
  • The locations page also carries retention_floor and schema_version. See Locations.
RuleWhat it means
OpaqueA cursor is a short ASCII string (at most 256 bytes; a us1_ users cursor at most 356) that starts with the list’s prefix (dc1_, us1_, lc1_, tr1_, gf1_, wh1_, ec1_). The one exception is the events feed on a project with no events yet: its next_cursor is an empty string, which counts as no cursor. Never build, edit or parse one; the only valid cursor is one the server returned to you.
One list onlyA cursor from one list is invalid on another, except that GET /v1/devices?user_id=<id> and GET /v1/users/<id>/devices share their cursors: one resumes on the other.
DurableCursors hold a position, not an offset, and survive server restarts. Store next_cursor after you finish processing a page, and you can resume from there later.
Bound to their queryA cursor is valid only for the query that produced it: the same project and the same filters (for a trip’s locations, the same trip). Changing a filter mid-walk is 400 cursor_query_mismatch rather than a silently meaningless page. Start a new walk instead. limit is not part of the query; changing it between pages is fine.
StatuserrorMeaning
400invalid_cursorNot a cursor this server issued for this resource: wrong prefix, edited, truncated, padded, or sent twice.
400cursor_query_mismatchA valid cursor, but for a different query.
410expired_cursorThe position has been deleted under retention.

Data older than your plan’s retention is deleted. If a locations or events walk is paused long enough for retention to overtake its position, the next request answers 410 expired_cursor. The gap is real and permanent — those items are gone. Restart: for locations, with a new from; for events, with no cursor.

410 is the only response that means “discard this cursor”. After a 5xx or a 429, retry with the same cursor.

Terminal window
cursor=""
while :; do
page=$(curl -sf -G https://api.in1.getbeekon.com/v1/locations \
-H "Authorization: Bearer $BEEKON_TOKEN" \
--data-urlencode "from=2026-10-06T00:00:00Z" \
--data-urlencode "to=2026-10-07T00:00:00Z" \
--data-urlencode "limit=500" \
--data-urlencode "cursor=$cursor") || break
echo "$page" | jq -c '.locations[]'
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -z "$cursor" ] && break
done