These endpoints read the trips the server cuts from each device’s admitted locations, with no
change to the SDK. A trip starts when a device moves away from where it stopped, and ends when it
stops again, when its locations stop arriving, when a new session starts or your app calls
stop(), or after a long silence (when a trip ends). The trips section of
your remote config sets how trips are cut.
GET /v1/trips
Section titled “GET /v1/trips”Scope: trips:read · Lists trips, paged, ordered by started_at, then
id. Open trips are included.
curl -s -G https://api.in1.getbeekon.com/v1/trips \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "install_id=2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50" \ --data-urlencode "from=2026-10-07T00:00:00Z" \ --data-urlencode "to=2026-10-08T00:00:00Z"| Parameter | Required | Meaning |
|---|---|---|
install_id | no | Only this device’s trips. Not blank, at most 128 bytes. |
from | no | Only trips still going at or after this instant: last_point_at ≥ from. RFC 3339, any offset. |
to | no | Only trips that started before this instant: started_at < to. RFC 3339, any offset. Must be after from when both are sent. |
limit | no | 1–500, default 100. |
cursor | no | The previous page’s next_cursor (prefix tr1_). |
from and to select every trip that overlaps the window, including a trip that began before
from or is still running at to. Either may be left out for an open-ended window. There is no
maximum window.
Response 200:
{"next_cursor": null, "trips": [{…}]}| Status | error | When |
|---|---|---|
| 400 | invalid_install_id | Blank, over 128 bytes, empty or repeated. |
| 400 | invalid_window | from or to unparseable (a bare date included), empty or repeated, or to not after from. |
| 400 | invalid_cursor · cursor_query_mismatch | A cursor this list did not issue, or one issued for other filters. |
| 400 | limit must be an integer in [1, 500] | Bad or repeated limit. |
GET /v1/trips/{trip_id}
Section titled “GET /v1/trips/{trip_id}”Scope: trips:read · Reads one trip.
curl -s \ https://api.in1.getbeekon.com/v1/trips/5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f \ -H "Authorization: Bearer $BEEKON_TOKEN"Response 200: {"trip":{…}}. An unknown or malformed id is 404 not found.
A trip’s locations
Section titled “A trip’s locations”GET /v1/trips/{trip_id}/points
Section titled “GET /v1/trips/{trip_id}/points”Scope: trips:read · The locations that make up the trip, in recorded order,
paged.
curl -s -G \ https://api.in1.getbeekon.com/v1/trips/5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f/points \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "limit=500"| Parameter | Required | Meaning |
|---|---|---|
limit | no | 1–500, default 100. |
cursor | no | The previous page’s next_cursor. Bound to this trip. |
Response 200:
{ "next_cursor": "tr1_…", "points": [ { "id": "0199b2c4-6a10-7d2e-8f31-4a5b6c7d8e9f", "accuracy_m": 8, "activity": "automotive", "device": {"install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50"}, "is_mock": false, "latitude": 12.9716, "longitude": 77.5946, "mode": "driving", "motion": "moving", "received_at": "2026-10-07T09:00:04.000Z", "recorded_at": "2026-10-07T09:00:00.000Z", "source": "sdk", "trigger": "motion", "trust_tier": "unverified" } ]}Each entry in points (the trip’s locations) is the same object
GET /v1/locations returns. Only the locations counted in
the trip appear: admitted locations that passed the trip filters. While a trip is open, its newest
locations may not be listed yet.
| Status | error | When |
|---|---|---|
| 400 | invalid_cursor · cursor_query_mismatch | A cursor this list did not issue, or one issued for another trip. |
| 400 | limit must be an integer in [1, 500] | Bad or repeated limit. |
The trip object
Section titled “The trip object”{ "id": "5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f", "distance_m": 5234.81, "duration_seconds": 1122, "end": {"latitude": 12.9352, "longitude": 77.6245}, "end_reason": "stop", "ended_at": "2026-10-07T09:18:42.000Z", "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "last_point_at": "2026-10-07T09:18:42.000Z", "mode": "driving", "mode_counts": {"driving": 41, "still": 3, "walking": 2}, "point_count": 46, "revision": 2, "settings_revision": 7, "start": {"latitude": 12.9716, "longitude": 77.5946}, "started_at": "2026-10-07T09:00:00.000Z", "status": "closed", "user_id": "acct_9931"}| Member | Type | Presence | Meaning |
|---|---|---|---|
id | string | always | The trip id, a UUID. Deterministic: the same trip always has the same id. |
install_id | string | always | The device. |
user_id | string | when set | The user id the device’s locations carried. A trip never mixes users: a change of user ends it. |
status | string | always | open (still in progress; its summary is provisional), stalled (an open trip whose device has gone quiet; see the trip lifecycle) or closed (final). |
started_at | string | always | The recorded time of the first location. |
last_point_at | string | always | The recorded time of the latest location counted so far. |
ended_at | string | closed only | Equal to last_point_at once closed. |
end_reason | string | closed only | Why the trip ended. See when a trip ends for each value: stop, gap, project_change, identity_change, session_change, tracking_stopped or silence. |
duration_seconds | integer | always | Whole seconds from the first location to the last. For an open or stalled trip, measured to last_point_at. |
distance_m | number | always | Path length over the trip’s locations, in metres. Not rounded. |
point_count | integer | always | Number of locations in the trip. Always at least 3. |
mode | string | always | The trip’s movement mode: driving, cycling, running, walking or unknown. |
mode_counts | object | always | Locations per mode; modes with no locations are left out. The counts add up to point_count. |
start | object | always | {latitude, longitude} of the first location. |
end | object | closed only | {latitude, longitude} of the last location. |
settings_revision | integer | always | The remote-config revision whose trip settings this trip was cut with. A later settings change never alters an existing trip. |
revision | integer | always | A change counter: 1 when the trip first appears, then +1 each time its locations, end, status or end_reason change, including each stall and each return from stalled to open. Compare it to know whether a cached trip changed. |
An open or stalled trip has no ended_at, end_reason or end. There is no project_id: every
trip you can read is in the token’s project. Ignore members you don’t know, and unknown status,
end_reason and mode values.
What can still change. Outside a rebuild, once a trip appears, its id,
install_id, user_id, started_at, start and settings_revision never change. Before it
closes, its status can move between open and stalled any number of times. It becomes
closed exactly once, from either, and never changes back. Once it is closed, its status,
ended_at, last_point_at, end, end_reason and duration_seconds never change either. A
closed trip’s point_count, distance_m, mode and mode_counts can still change when a late
location from an offline device lands inside it, and revision goes up when they do. A trip is
removed only by retention, a data-erasure request or a rebuild.
The trip lifecycle
Section titled “The trip lifecycle”A trip is open from the moment it is stored. Two things can happen while it is open:
| From | To | When | Event |
|---|---|---|---|
open | stalled | The device has had no contact for trips.silence_timeout_seconds, or the server declares it unreachable. | trip.stalled |
stalled | open | New locations from the device extend the trip. | none (watch status and revision) |
open or stalled | closed | Any of the reasons in when a trip ends. | trip.ended |
Contact means any upload the server accepts from the SDK on that device, including a
heartbeat or an upload with no locations. Uploads you make with a server key through
POST /v1/ingest are not contact. The silence is measured from the device’s
last contact, not from last_point_at, so a resting device that keeps sending heartbeats does
not stall its trip.
A stall is the server’s guess that the trip has probably ended. It never moves the trip’s end:
the trip’s locations, last_point_at and summary stay as they were, and a later upload can still
extend it or close it at its real end. A contact without locations (a heartbeat, or the device
becoming reachable again) does not return a stalled trip to open; only locations that extend
the trip do.
Both timeouts are in the trips section of your remote config:
| Setting | Default | Meaning |
|---|---|---|
silence_timeout_seconds | the effective max_gap_seconds (600 unless you changed it) | No contact for this long marks an open trip stalled. 0 turns the silence stall off; a trip still stalls when its device is declared unreachable. |
finality_timeout_seconds | 86400 (24 hours) | No contact for this long closes an open or stalled trip with end_reason: silence. |
A device whose locations reach Beekon only through server-key uploads has no contact, so its trips
never stall and never close with silence. They end on what the locations show.
When a trip ends
Section titled “When a trip ends”A trip ends once, for one of these reasons:
end_reason | What ended it |
|---|---|
stop | The device stayed in one place long enough (stop_radius_meters for stop_duration_seconds), or the SDK reported that the device is resting (SDK 0.6.0 and later). |
gap | Its locations stopped arriving for longer than max_gap_seconds. The trip closes when the device’s next location arrives, ending at the last location before the silence. |
identity_change | The device’s locations started carrying another user id. |
project_change | The device’s locations started arriving under another project. |
session_change | Your app started a new tracking session. Each call to start() begins one, so calling stop() and start() mid-journey splits the trip: each part is a trip only if it is long enough on its own. An app that is killed and revived by the system keeps its session, so that does not split a trip. |
tracking_stopped | Your app called stop(). The SDK reports the stop with its next upload (or a small upload of its own when nothing is queued), and the server closes the trip at its last location. In the in1 region that happens within seconds of the report; in other regions it can wait until the region next handles traffic. |
silence | The device has had no contact for finality_timeout_seconds. The server closes the trip at its last location. If the device later uploads locations from the same journey, they start a new trip. |
An app that knows when its trips end should call stop(): it gets a prompt and final
trip.ended with tracking_stopped. A device whose stop() report never arrives (an SDK before
0.5.0, or a device lost with the report queued) still closes its trip with session_change the
next time it tracks, or with silence once finality_timeout_seconds has passed.
Events
Section titled “Events”Beekon sends a trip.started event when a trip is first stored, a
trip.stalled event each time an open trip
stalls, and a trip.ended event when it is first closed. Each carries the trip object as it was
then. Subscribe to them with a webhook, or read them from
GET /v1/events.
Rebuilds
Section titled “Rebuilds”An operator can re-cut a device’s stored trips from its locations under the project’s current trip settings, for example after a settings change. A rebuild can change or remove trip ids. It is never automatic and never triggered by your API calls. After a rebuild:
- A trip whose first location is unchanged keeps its
id, and itsrevisiongoes up if anything about it changed. - A trip the rebuild no longer produces is deleted.
- New trips appear with new ids and
revision1. - Every rebuilt trip reports the current
settings_revision. - A trip that was
stalledcomes backopen; it stalls again if its device is still quiet.
A rebuild sends no event or webhook: if you cache trips by id, re-read the device’s trips when
you are told a rebuild ran.
Errors on every trip endpoint
Section titled “Errors on every trip endpoint”| Status | error | When |
|---|---|---|
| 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 trips:read. |
| 404 | not found | Unknown, foreign or malformed trip id. |
| 500 | internal error | A failure on our side. Retry with the same cursor. |