GET /v1/locations reads the locations your devices uploaded, for a time window, in the
order the devices recorded them. Locations the server judged unusable (mock locations, poor accuracy,
impossible speed) are stored too and can be read on request, each with the reason. To keep a copy
of every location as it arrives, read GET /v1/locations/feed instead.
GET /v1/locations
Section titled “GET /v1/locations”Scope: locations:read
curl -s -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=100"Parameters
Section titled “Parameters”All parameters ride the query string. Parameters this endpoint does not define are ignored. A
defined parameter sent twice is a 400 with that parameter’s error, and an empty value is a
400 — except limit= and cursor=, which count as absent.
| Parameter | Required | Meaning |
|---|---|---|
from | yes | Inclusive start of the window, on the device’s recorded time. |
to | yes | Exclusive end of the window. Must be after from. |
install_id | no | Only this device. Max 128 bytes; must not be blank or contain a NUL character. |
user_id | no | Only locations recorded under this user id (the value your app set in the SDK). Max 256 bytes, valid UTF-8, no control characters. Matched exactly, with no trimming. |
include_gated | no | true to include locations the server gated, alongside admitted ones. false (the default) returns admitted locations only. Exactly true or false, lowercase. |
gate_reason | no | Only locations gated for this reason: low_accuracy, implausible_speed or mock. Cannot be combined with include_gated. |
mode | no | Only locations with this movement mode: still, walking, running, cycling, driving or unknown. One value; a list is refused. |
order | no | asc (the default): oldest first. desc: newest first — the latest locations of a long window in one request. Exactly asc or desc, lowercase. See Newest first. |
limit | no | 1–500, default 100. See Pagination. |
cursor | no | The previous page’s next_cursor. |
The window. from and to are RFC 3339 timestamps with any offset — 2026-10-07T15:00:00+05:30
and 2026-10-07T09:30:00Z are the same instant. A bare date (2026-10-07) is refused, never read as
midnight. The window is half-open: a location recorded exactly at from is included and one exactly
at to is not, so consecutive windows ([a, b), [b, c)) tile with no overlap and no gap.
Filters combine with AND. install_id=X&user_id=Y returns locations from device X recorded under
user Y.
The 24-hour cap
Section titled “The 24-hour cap”install_id, user_id, gate_reason and mode are selective filters. When any of them is present,
to − from must be at most 24 hours (exactly 24 hours is allowed), or the request is
400 window_too_large — the window is never silently narrowed. To read a longer period for one
device, walk consecutive 24-hour windows. A read without those filters has no maximum window.
Response
Section titled “Response”{ "locations": [ { "id": "01900100-0000-7000-8000-000000000001", "accuracy_m": 12.5, "activity": "walking", "altitude_m": 920.25, "battery_percent": 63, "bearing_deg": 271.5, "device": { "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "session_id": "sess-1", "user_id": "acct_9931" }, "extras": {"fleet": "north", "route": "R-12"}, "is_charging": true, "is_mock": false, "latitude": 12.9716, "longitude": 77.5946, "mode": "walking", "motion": "moving", "power_save_mode": false, "received_at": "2026-08-06T07:06:45.000Z", "recorded_at": "2026-08-06T07:06:41.000Z", "source": "sdk", "speed_mps": 1.4, "trigger": "check_in", "trust_tier": "unverified" } ], "next_cursor": null, "retention_floor": null, "schema_version": 1}(Pretty-printed here; the API sends compact JSON.)
| Member | Type | Meaning |
|---|---|---|
locations | array | The locations, ordered by recorded_at ascending (ties broken by id), or descending with order=desc. [] when empty. |
next_cursor | string | null | The cursor for the next page, or null when the window is exhausted. |
retention_floor | string | null | The earliest instant your project’s data is still kept from, or null if nothing has ever been deleted under retention. See Retention. |
schema_version | integer | 1. |
The location object
Section titled “The location object”| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | always | The location’s id, minted by the device: a lowercase UUID of any version. Unique only together with recorded_at. |
recorded_at | string | always | When the device recorded the fix. |
received_at | string | always | When the server stored it. Can be earlier than recorded_at if the device clock is wrong. |
device | object | always | install_id (always) · session_id (when the SDK set one) · user_id (when the SDK had a user id set at record time). |
latitude, longitude | number | always | Degrees. |
accuracy_m | number | optional | Horizontal accuracy, metres. |
altitude_m | number | optional | Metres. |
speed_mps | number | optional | Metres per second. |
bearing_deg | number | optional | Degrees. |
activity | string | optional | The device’s raw activity reading: stationary, walking, running, cycling, automotive or unknown. Absent when activity detection is off. |
mode | string | always | The normalised movement mode derived from activity: still, walking, running, cycling, driving or unknown. |
quality | string | optional | The device’s own opinion of the fix: low_accuracy or implausible_speed. Absent when the device considered it good. Not the server’s verdict — see gate. |
battery_percent | integer | optional | 0–100. 0 is a real reading. |
is_charging, power_save_mode | boolean | optional | As reported by the device. |
is_mock | boolean | always | The OS flagged this fix as a mock location. |
trigger | string | always | Why the fix was taken: interval, motion, check_in, geofence or manual. |
motion | string | always | moving, stationary or unknown. |
source | string | always | Who produced the location: sdk (the SDK on a device) or server (uploaded with a server key through POST /v1/ingest). |
trust_tier | string | always | unverified, attested or verified. Independent of is_mock. |
extras | object | optional | Your own string-to-string map, exactly as your app attached it. Treat it as untrusted input. |
gate | object | gated locations only | {"reason": "low_accuracy" | "implausible_speed" | "mock"}. Absent means admitted. |
Optional members are omitted when absent — never null. There is no project_id on a location: the
whole page is your project.
Forward compatibility. Ignore members you don’t know, and unknown values of activity,
mode, trigger, motion and source. The one exception is gate.reason: if you meet a reason you don’t
know, treat the location as gated, never as admitted.
Admitted and gated locations
Section titled “Admitted and gated locations”The server checks every uploaded location. A location it judges unusable is gated: it is stored unchanged, with a reason, and kept out of the default view.
| You send | You get |
|---|---|
neither include_gated nor gate_reason | admitted locations only |
include_gated=true | admitted and gated locations together, in one order; gated ones carry gate |
gate_reason=mock | only locations gated as mock |
This is how you answer “why isn’t my location showing up?” — re-run the window with
include_gated=true and look for a gate.
Ordering and completeness
Section titled “Ordering and completeness”Locations are ordered by the device’s recorded time, not by arrival. Within one walk you get no duplicates and no skips over the locations stored when each page was served.
Devices upload offline-first, so a device that was out of coverage delivers locations dated in the
past — possibly into a window you already walked. Those locations will not appear in that finished
walk. To reconcile, re-run the window later, or keep a copy with
GET /v1/locations/feed, which is ordered by arrival and never skips a
late location. (Geofence events work the same way: GET /v1/events is ordered by
arrival and guarantees that a walk never skips an event.)
A walk over a window whose to is in the past always ends (next_cursor: null). A to in the
future is allowed, but the walk may keep finding new locations.
Newest first
Section titled “Newest first”order=desc reads the same window, with the same filters and limit, newest first: the first page
holds the window’s latest locations, and each next_cursor continues toward from. The guarantees
above hold in reverse — no duplicates, no skips — and so does the caveat: a location that arrives
dated after a position you already passed will not appear in that walk.
curl -s -G https://api.in1.getbeekon.com/v1/locations \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "from=2026-10-01T00:00:00Z" \ --data-urlencode "to=2026-10-07T00:00:00Z" \ --data-urlencode "order=desc" \ --data-urlencode "limit=50"A cursor belongs to its direction: send it back with the same order (or, for an oldest-first
walk, with none — order=asc and no order are the same request). A cursor from one direction
sent with the other is 400 cursor_query_mismatch.
GET /v1/locations/feed
Section titled “GET /v1/locations/feed”Scope: locations:read
The feed serves every location of your project once, in the order the server finished checking
it, so you can keep a copy of your locations up to date. A device that was offline delivers
locations recorded long ago; in the feed they appear after the cursor you already hold, never
before it. Within one upload, locations are ordered by recorded_at, then id.
curl -s -G https://api.in1.getbeekon.com/v1/locations/feed \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "cursor=$CURSOR" \ --data-urlencode "limit=500"| Parameter | Required | Meaning |
|---|---|---|
include_gated | no | true adds gated locations, each with gate, to admitted ones. false (the default) returns admitted locations only. Exactly true or false. |
limit | no | 1–500, default 100. |
cursor | no | The previous page’s next_cursor (prefix lf1_). Absent or empty starts at the oldest position the feed still keeps. |
The feed has no window and no filters: from, to, install_id, user_id, gate_reason,
mode and order are ignored. The page has the same four members and the same
location object as GET /v1/locations, with one difference:
next_cursor is never null. Store it and send it on the next call. An empty page means
nothing new has arrived yet; poll again later with the same cursor.
What you can rely on.
- A location is served only once the server has decided whether it is admitted or gated, so its
gatenever changes after you read it. - The feed keeps positions for 7 days. A cursor older than that is
410 expired_cursor: start again without a cursor and fill the gap withGET /v1/locationswindows. - Locations recorded below
retention_floorare never served. - Locations stored before the feed existed are not in it. Read them with
GET /v1/locations. - A location can be served twice after an operator re-admits it, so deduplicate on
(id, recorded_at). - A cursor belongs to its project. One from another project is
400 cursor_query_mismatch.
| Status | error | When |
|---|---|---|
| 400 | invalid_include_gated | Not exactly true or false, or repeated. |
| 400 | invalid_cursor | Not a feed cursor this server issued, or repeated. |
| 400 | cursor_query_mismatch | The cursor was issued for another project. |
| 400 | limit must be an integer in [1, 500] | Bad or repeated limit. |
| 401 | missing bearer token · invalid session token | No valid session. |
| 403 | server credentials required | The token was minted from an SDK key. |
| 403 | insufficient scope | The key lacks locations:read. |
| 410 | expired_cursor | The cursor is older than the feed’s 7 days. |
| 500 | internal error | A failure on our side. Retry with the same cursor. |
Retention
Section titled “Retention”Locations older than your plan’s retention are deleted, and retention_floor on each page tells you
the boundary.
- A
frombelow the floor is narrowed, not refused: you get the window from the floor onwards. Compareretention_floorwith yourfrom— if yourfromis earlier, the difference is a permanent gap. - A page never contains a location earlier than its own
retention_floor. - A cursor whose position has fallen below the floor is
410 expired_cursor. Restart with a newfrom.
Errors
Section titled “Errors”| Status | error | When |
|---|---|---|
| 400 | invalid_window | from or to missing, unparseable (a bare date included), repeated, or to not after from. |
| 400 | window_too_large | install_id, user_id, gate_reason or mode present and the window is longer than 24 hours. |
| 400 | invalid_install_id | Blank, over 128 bytes, containing a NUL character, or repeated. |
| 400 | invalid_user_id | Empty, over 256 bytes, invalid UTF-8, a control character, or repeated. |
| 400 | invalid_gate_reason | Not one of the three reasons, or repeated. |
| 400 | invalid_mode | Not exactly one of the six modes (case-sensitive), empty, a comma list, or repeated. |
| 400 | invalid_include_gated | Not exactly true or false, empty, or repeated. |
| 400 | invalid_order | Not exactly asc or desc (case-sensitive), empty, or repeated. |
| 400 | conflicting_filters | gate_reason sent together with include_gated. |
| 400 | invalid_cursor | Not a locations cursor this server issued, or repeated. |
| 400 | cursor_query_mismatch | The cursor was issued for a different window, filters or order. |
| 400 | limit must be an integer in [1, 500] | Bad or repeated limit. |
| 401 | missing bearer token · invalid session token | No valid session. |
| 403 | the location log is readable by server integrator credentials only | The token was minted from an SDK key. |
| 403 | insufficient scope | The key lacks locations:read. |
| 410 | expired_cursor | The cursor’s position is below the retention floor. |
| 500 | internal error | A failure on our side. Retry with the same cursor. |