Skip to content

Trips

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.

Scope: trips:read · Lists trips, paged, ordered by started_at, then id. Open trips are included.

Terminal window
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"
ParameterRequiredMeaning
install_idnoOnly this device’s trips. Not blank, at most 128 bytes.
fromnoOnly trips still going at or after this instant: last_point_at ≥ from. RFC 3339, any offset.
tonoOnly trips that started before this instant: started_at < to. RFC 3339, any offset. Must be after from when both are sent.
limitno1–500, default 100.
cursornoThe 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": [{…}]}
StatuserrorWhen
400invalid_install_idBlank, over 128 bytes, empty or repeated.
400invalid_windowfrom or to unparseable (a bare date included), empty or repeated, or to not after from.
400invalid_cursor · cursor_query_mismatchA cursor this list did not issue, or one issued for other filters.
400limit must be an integer in [1, 500]Bad or repeated limit.

Scope: trips:read · Reads one trip.

Terminal window
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.

Scope: trips:read · The locations that make up the trip, in recorded order, paged.

Terminal window
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"
ParameterRequiredMeaning
limitno1–500, default 100.
cursornoThe 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.

StatuserrorWhen
400invalid_cursor · cursor_query_mismatchA cursor this list did not issue, or one issued for another trip.
400limit must be an integer in [1, 500]Bad or repeated limit.
{
"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"
}
MemberTypePresenceMeaning
idstringalwaysThe trip id, a UUID. Deterministic: the same trip always has the same id.
install_idstringalwaysThe device.
user_idstringwhen setThe user id the device’s locations carried. A trip never mixes users: a change of user ends it.
statusstringalwaysopen (still in progress; its summary is provisional), stalled (an open trip whose device has gone quiet; see the trip lifecycle) or closed (final).
started_atstringalwaysThe recorded time of the first location.
last_point_atstringalwaysThe recorded time of the latest location counted so far.
ended_atstringclosed onlyEqual to last_point_at once closed.
end_reasonstringclosed onlyWhy the trip ended. See when a trip ends for each value: stop, gap, project_change, identity_change, session_change, tracking_stopped or silence.
duration_secondsintegeralwaysWhole seconds from the first location to the last. For an open or stalled trip, measured to last_point_at.
distance_mnumberalwaysPath length over the trip’s locations, in metres. Not rounded.
point_countintegeralwaysNumber of locations in the trip. Always at least 3.
modestringalwaysThe trip’s movement mode: driving, cycling, running, walking or unknown.
mode_countsobjectalwaysLocations per mode; modes with no locations are left out. The counts add up to point_count.
startobjectalways{latitude, longitude} of the first location.
endobjectclosed only{latitude, longitude} of the last location.
settings_revisionintegeralwaysThe remote-config revision whose trip settings this trip was cut with. A later settings change never alters an existing trip.
revisionintegeralwaysA 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.

A trip is open from the moment it is stored. Two things can happen while it is open:

FromToWhenEvent
openstalledThe device has had no contact for trips.silence_timeout_seconds, or the server declares it unreachable.trip.stalled
stalledopenNew locations from the device extend the trip.none (watch status and revision)
open or stalledclosedAny 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:

SettingDefaultMeaning
silence_timeout_secondsthe 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_seconds86400 (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.

A trip ends once, for one of these reasons:

end_reasonWhat ended it
stopThe 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).
gapIts 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_changeThe device’s locations started carrying another user id.
project_changeThe device’s locations started arriving under another project.
session_changeYour 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_stoppedYour 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.
silenceThe 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.

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.

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 its revision goes up if anything about it changed.
  • A trip the rebuild no longer produces is deleted.
  • New trips appear with new ids and revision 1.
  • Every rebuilt trip reports the current settings_revision.
  • A trip that was stalled comes back open; 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.

StatuserrorWhen
401missing bearer token · invalid session tokenNo valid session.
403server credentials requiredThe token was minted from an SDK key.
403insufficient scopeThe key lacks trips:read.
404not foundUnknown, foreign or malformed trip id.
500internal errorA failure on our side. Retry with the same cursor.