# Pagination

> How every /v1 list pages — limit 1–500, opaque cursors bound to their query, next_cursor null at the end, cursor_query_mismatch, and 410 expired_cursor.

Source: https://docs.getbeekon.com/api/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:

```sh
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](#a-complete-walk).

## 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

| List                                                              | Items member | Filters                    | Order                    | Cursor prefix |
| ----------------------------------------------------------------- | ------------ | -------------------------- | ------------------------ | ------------- |
| [`GET /v1/devices`](https://docs.getbeekon.com/api/devices/)                                | `devices`    | `user_id`                  | `install_id`, byte order | `dc1_`        |
| [`GET /v1/users`](https://docs.getbeekon.com/api/users/)                                    | `users`      | none                       | `user_id`, byte order    | `us1_`        |
| [`GET /v1/users/{user_id}/devices`](https://docs.getbeekon.com/api/users/#a-users-devices)  | `devices`    | the user                   | `install_id`, byte order | `dc1_`        |
| [`GET /v1/locations`](https://docs.getbeekon.com/api/locations/)                            | `locations`  | window and filters         | `recorded_at`, then `id` | `lc1_`        |
| [`GET /v1/locations/feed`](https://docs.getbeekon.com/api/locations/#get-v1locationsfeed)   | `locations`  | `include_gated`            | arrival                  | `lf1_`        |
| [`GET /v1/trips`](https://docs.getbeekon.com/api/trips/)                                    | `trips`      | `install_id`, `from`, `to` | `started_at`, then `id`  | `tr1_`        |
| [`GET /v1/trips/{trip_id}/points`](https://docs.getbeekon.com/api/trips/#a-trips-locations) | `points`     | the trip                   | `recorded_at`, then `id` | `tr1_`        |
| [`GET /v1/geofences`](https://docs.getbeekon.com/api/geofences/)                            | `geofences`  | none                       | `id`                     | `gf1_`        |
| [`GET /v1/webhooks`](https://docs.getbeekon.com/api/webhooks/)                              | `webhooks`   | none                       | `created_at`, then `id`  | `wh1_`        |
| [`GET /v1/events`](https://docs.getbeekon.com/api/events/)                                  | `events`     | none                       | log order                | `ec1_`        |

## The page

```jsonc
{"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](https://docs.getbeekon.com/api/locations/#response).

Feeds page differently

[`GET /v1/events`](https://docs.getbeekon.com/api/events/) and [`GET /v1/locations/feed`](https://docs.getbeekon.com/api/locations/#get-v1locationsfeed) are never-ending feeds, not finite lists, so their `next_cursor` is **never `null`**: an empty page returns the cursor you sent, and you poll again later with it. Don’t share a page parser between the feeds and the other lists.

## 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)

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

```sh
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
```
