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:
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 pageA loop that walks a whole list is in A complete walk.
Parameters
Section titled “Parameters”| Parameter | Rule |
|---|---|
limit | An 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. |
cursor | The 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.
The lists
Section titled “The lists”| List | Items member | Filters | Order | Cursor prefix |
|---|---|---|---|---|
GET /v1/devices | devices | user_id | install_id, byte order | dc1_ |
GET /v1/users | users | none | user_id, byte order | us1_ |
GET /v1/users/{user_id}/devices | devices | the user | install_id, byte order | dc1_ |
GET /v1/locations | locations | window and filters | recorded_at, then id | lc1_ |
GET /v1/locations/feed | locations | include_gated | arrival | lf1_ |
GET /v1/trips | trips | install_id, from, to | started_at, then id | tr1_ |
GET /v1/trips/{trip_id}/points | points | the trip | recorded_at, then id | tr1_ |
GET /v1/geofences | geofences | none | id | gf1_ |
GET /v1/webhooks | webhooks | none | created_at, then id | wh1_ |
GET /v1/events | events | none | log order | ec1_ |
The page
Section titled “The page”{"devices":[…],"next_cursor":"dc1_AAYs…"}- The items array is always present, and is
[]when there is nothing to return. next_cursoris always present. It is a string while more items exist, andnullwhen the walk is complete.next_cursoris decided by whether another item exists, not by whether the page is full: a list of exactlylimititems completes in one page. Always loop onnext_cursor, not on the item count.- The locations page also carries
retention_floorandschema_version. See Locations.
Cursors
Section titled “Cursors”| Rule | What it means |
|---|---|
| Opaque | A 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 only | A 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. |
| Durable | Cursors 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 query | A 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. |
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_cursor | Not a cursor this server issued for this resource: wrong prefix, edited, truncated, padded, or sent twice. |
| 400 | cursor_query_mismatch | A valid cursor, but for a different query. |
| 410 | expired_cursor | The position has been deleted under retention. |
Expired cursors (410)
Section titled “Expired cursors (410)”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.
A complete walk
Section titled “A complete walk”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" ] && breakdone