Beekon records an event when the server decides that a device entered, left or dwelt in one of your geofences, when a trip starts, stalls or ends, when a device stops or starts being reachable, and when your project crosses a usage threshold. Events reach you two ways, carrying the same event objects:
- Webhooks push them to your endpoint as they happen. See Webhooks.
GET /v1/eventslets you pull them. It is the source of truth for catching up on anything a webhook endpoint missed.
GET /v1/events
Section titled “GET /v1/events”Scope: events:read
curl -s -G https://api.in1.getbeekon.com/v1/events \ -H "Authorization: Bearer $BEEKON_TOKEN" \ --data-urlencode "limit=100" \ --data-urlencode "cursor=$EVENTS_CURSOR"Parameters
Section titled “Parameters”| Parameter | Required | Meaning |
|---|---|---|
cursor | no | The next_cursor from your previous page. Absent or empty: start from the oldest event still retained. |
limit | no | 1–500, default 100. Out of range or not an integer: 400 limit must be an integer in [1, 500]. Sent twice, the first is read. |
There are no filters: the feed is project-wide and includes every stored event type (geofence,
trip, device presence and usage threshold events). Filter by type on your side.
Response
Section titled “Response”{ "events": [ { "id": "019e9f61-1400-7000-8000-0000000000e1", "type": "geofence.enter", "detected_at": "2026-06-07T00:00:02.000Z", "device": {"install_id": "install-e1"}, "evidence": "track", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"}, "location": { "accuracy_m": 12.5, "latitude": 12.9716, "longitude": 77.5946, "recorded_at": "2026-06-07T00:00:00.000Z" }, "occurred_at": "2026-06-07T00:00:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1" } ], "next_cursor": "ec1_…", "schema_version": 1}| Member | Type | Meaning |
|---|---|---|
events | array | Event objects in log order: the order the server committed them, not occurred_at order. |
next_cursor | string | Always present, never null. Send it as cursor on your next request. |
schema_version | integer | 1. If you meet a value you don’t understand, stop and fail loudly. |
How the feed behaves
Section titled “How the feed behaves”- It never ends. When you have caught up, you get an empty
eventsarray and the same cursor you sent. Wait, then poll again with it. (On a project with no events yet, polling with no cursor returns an emptynext_cursor; keep polling with no cursor.) - It never skips. If you only ever advance by sending back
next_cursor, you will never permanently miss an event. To guarantee that, the newest events can appear a moment late, while they are still being committed: a short lag, never a loss. - Store the cursor after processing. Save
next_cursordurably once you have processed a page, and you get exactly-once processing of the feed. - Don’t derive a cursor from an event’s
id; onlynext_cursoris valid. - Retention. Events stay readable here for at least 7 days after they are produced; your
plan may keep them longer. A cursor older than that answers
410 expired_cursor: restart with no cursor, and treat the gap as real.
Errors
Section titled “Errors”| Status | error | When |
|---|---|---|
| 400 | invalid_cursor | Not an events cursor this server issued. |
| 400 | limit must be an integer in [1, 500] | Bad limit. |
| 401 | missing bearer token · invalid session token | No valid session. |
| 403 | the event log is readable by server integrator credentials only | The token was minted from an SDK key. |
| 403 | insufficient scope | The key lacks events:read. |
| 410 | expired_cursor | The cursor is older than retention. Restart with no cursor. |
| 500 | internal error | A failure on our side. Retry with the same cursor. |
| 503 | credential status unavailable | The server could not read whether the key is still active. Retry with the same cursor after Retry-After. |
Event types
Section titled “Event types”type | Produced when |
|---|---|
geofence.enter | The server confirms that a device entered a geofence. See Geofence events. |
geofence.exit | The server confirms that a device left a geofence, or, for a fence set to on_unreachable: exit, that a device inside it became unreachable. |
geofence.dwell | A device stayed inside a geofence for 5 minutes, the one dwell time. |
trip.started | A device’s trip was first stored. See Trip events. |
trip.stalled | An open trip’s device went quiet. |
trip.ended | A stored trip was first closed. |
device.unreachable | A device with a fence visit or a trip in progress stopped being reachable. See Device presence events. |
device.reachable | That device was heard from again. |
billing.usage_threshold | The project’s monthly active users (MAU) crossed 50%, 80% or 100% of your configured cap. An alert: usage goes on past the cap. |
webhook.ping | You asked for a test delivery. Webhooks only: never stored, never in GET /v1/events. |
New types may be added. Skip an event whose type you don’t know: never fail the page or the
webhook delivery because of it. A webhook endpoint with event_types: null receives every type,
including types added later.
Geofence events
Section titled “Geofence events”The server decides geofence events from the device’s uploaded locations, by the rules in
What produces a geofence event. A crossing the
device notices while tracking is stopped still notifies on the device, but the server has no
locations for it, so it records no event. The exception is a fence set to
on_unreachable: exit, which can send an exit when the device
stops tracking inside it. See Geofencing.
An enter confirmed by the device’s locations:
{ "id": "019e9f61-1400-7000-8000-0000000000e1", "type": "geofence.enter", "detected_at": "2026-06-07T00:00:02.000Z", "device": {"install_id": "install-e1", "user_id": "acct_9931"}, "evidence": "track", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"}, "location": { "accuracy_m": 12.5, "latitude": 12.9716, "longitude": 77.5946, "recorded_at": "2026-06-07T00:00:00.000Z" }, "occurred_at": "2026-06-07T00:00:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1"}A dwell, five minutes after that enter. dwell_seconds is the threshold that was crossed, and
location is the latest location inside the fence:
{ "id": "019e9f65-ee00-7000-8000-0000000000e5", "type": "geofence.dwell", "detected_at": "2026-06-07T00:05:02.000Z", "device": {"install_id": "install-e1", "user_id": "acct_9931"}, "dwell_seconds": 300, "evidence": "track", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"}, "location": { "accuracy_m": 10, "latitude": 12.9717, "longitude": 77.5947, "recorded_at": "2026-06-07T00:04:50.000Z" }, "occurred_at": "2026-06-07T00:05:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1"}An exit sent because the device became unreachable inside a fence set to on_unreachable: exit.
It has no location, and the exit happened between occurred_after and occurred_at:
{ "id": "019ea0c2-5b00-7000-8000-0000000000e2", "type": "geofence.exit", "detected_at": "2026-06-07T02:00:41.000Z", "device": {"install_id": "install-e1", "user_id": "acct_9931"}, "evidence": "unreachable", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"}, "occurred_after": "2026-06-06T13:59:58.000Z", "occurred_at": "2026-06-07T02:00:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1"}An enter the SDK reported itself, confirmed at once by a location in the same upload:
{ "id": "019ea2a4-1c00-7000-8000-0000000000e3", "type": "geofence.enter", "detected_at": "2026-06-07T08:30:03.000Z", "device": {"install_id": "install-e1", "user_id": "acct_9931"}, "evidence": "corroborated", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f1"}, "location": { "accuracy_m": 18, "latitude": 12.9717, "longitude": 77.5945, "recorded_at": "2026-06-07T08:29:40.000Z" }, "occurred_at": "2026-06-07T08:29:40.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1"}The enter of a drive-through on a fence set to pass_through: on. Neither location was inside;
occurred_at is where the line between them went in, so it is before location.recorded_at. Its
geofence.exit carries the same location:
{ "id": "019ea2c5-7e00-7000-8000-0000000000e4", "type": "geofence.enter", "detected_at": "2026-06-07T09:05:21.000Z", "device": {"install_id": "install-e1", "user_id": "acct_9931"}, "evidence": "interpolated", "geofence": {"id": "019000f0-0000-7000-8000-0000000000f2"}, "location": { "accuracy_m": 8, "latitude": 12.9741, "longitude": 77.6012, "recorded_at": "2026-06-07T09:05:00.000Z" }, "occurred_at": "2026-06-07T09:04:52.300Z", "project_id": "019000b0-0000-7000-8000-0000000000b1"}| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | always | The event id (a UUIDv7). Your deduplication key: a redelivered event keeps its id. |
type | string | always | geofence.enter, geofence.exit or geofence.dwell. |
occurred_at | string | always | When the crossing happened, not when it was evaluated or delivered. Which instant depends on evidence (table below); for a dwell, the instant the dwell time was reached. |
detected_at | string | always | When the server produced the event, on the server’s clock. At or after occurred_at, unless the device’s clock ran ahead of the server’s. Far after it for a late event or an upload that arrived late. |
project_id | string | always | Your project. |
device | object | always | install_id (always) · user_id (when the triggering location carried one) · session_id (when set). For an unreachable exit, the triggering location is the last one inside the fence. |
geofence | object | always | id, the geofence’s id. An external_id member is reserved: it appears only for a fence authored with one, which no endpoint offers yet. |
evidence | string | always | What the server’s decision rests on: track, interpolated, corroborated or unreachable (table below). Read a value you don’t know as “decided by the server, evidence unknown”. |
location | object | always, except evidence: unreachable | The triggering location: latitude, longitude, recorded_at, and accuracy_m when the location had an accuracy. For a dwell, the latest location inside the fence when the dwell time was reached. Absent (never null) on an unreachable exit. |
occurred_after | string | unreachable exits only | The recorded time of the device’s last location inside the fence. The exit happened after it and at or before occurred_at. |
late | boolean | only as true | The event belongs to a complete visit rebuilt from locations that arrived late. It never describes where the device is now. See late locations. |
dwell_seconds | number | dwell only | The dwell threshold that was crossed (not the total stay): 300 today, the same for every project. |
Evidence
evidence | Meaning | location | occurred_at |
|---|---|---|---|
track | The device’s admitted locations alone confirmed it. | The confirming location (dwell: the latest location inside) | The confirming location’s recorded time (dwell: when the dwell time was reached) |
corroborated | The device reported the crossing itself, and an admitted location in the same upload that does not contradict it confirmed it at once. | That location | That location’s recorded time |
interpolated | A pass-through: two consecutive locations outside the fence whose straight line crosses it. Only for a fence with pass_through: on. | The first location after the crossing | An instant between the two locations, so before location.recorded_at |
unreachable | The device was confirmed inside, then became unreachable. geofence.exit only, and only for a fence with on_unreachable: exit. | absent | The occurred_at of the device.unreachable that caused it |
A project whose fences all keep the default policies (pass_through: off,
on_unreachable: none) never receives interpolated or unreachable, so every geofence event it
receives has a location. See fence policies.
- Dwell. At most one
geofence.dwellper visit. There is one threshold, and it is not configurable; another dwell needs an exit first. A dwell can fire for a device that has stopped sending locations, so itslocation.recorded_atcan be well beforeoccurred_at. It is not sent for a device that became unreachable before the dwell time was reached, nor while its visit is unverified (see fence policies). - The device’s own crossings never produce an event alone. They only let an admitted location
confirm a crossing at once (
corroborated), never against a location that contradicts them.
Late locations
A location is late when it is recorded before the newest location the server has already evaluated for that device, for example when an offline device uploads its backlog after newer locations. Late locations never change the device’s current state in a fence.
When late locations recorded within 72 hours before the newest
evaluated location show a complete visit (an enter and an exit of the same fence) that does
not overlap a visit already sent, Beekon sends both events with late: true. An incomplete visit
sends nothing, a late visit never produces a dwell, and locations more than 72 hours behind
produce no events. All late locations are stored and readable on
GET /v1/locations.
Trip events
Section titled “Trip events”Beekon produces trip events on the server, from the same trip detection as
GET /v1/trips. The SDK needs no change.
A trip.started, for a trip that is still open:
{ "id": "01a11597-4e80-7a3c-9d21-6b5e4f3a2c10", "type": "trip.started", "detected_at": "2026-10-07T09:00:34.000Z", "device": { "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "user_id": "acct_9931" }, "occurred_at": "2026-10-07T09:00:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1", "trip": { "id": "5b0d3c6e-2f1a-8c4d-9e7f-0a1b2c3d4e5f", "distance_m": 182.4, "duration_seconds": 30, "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "last_point_at": "2026-10-07T09:00:30.000Z", "mode": "driving", "mode_counts": {"driving": 3}, "point_count": 3, "revision": 1, "settings_revision": 7, "start": {"latitude": 12.9716, "longitude": 77.5946}, "started_at": "2026-10-07T09:00:00.000Z", "status": "open", "user_id": "acct_9931" }}The trip.ended for the same trip:
{ "id": "01a115a8-6d50-7b4d-8e32-7c6f5a4b3d21", "type": "trip.ended", "detected_at": "2026-10-07T09:18:44.000Z", "device": { "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "user_id": "acct_9931" }, "occurred_at": "2026-10-07T09:18:42.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1", "trip": { "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" }}A trip.stalled for another trip, whose device
went quiet at 14:02 and stayed silent for the default 600 seconds:
{ "id": "01a11702-91c0-7e4a-8b16-2d3c4b5a6f70", "type": "trip.stalled", "detected_at": "2026-10-07T14:12:31.000Z", "device": { "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "user_id": "acct_9931" }, "occurred_at": "2026-10-07T14:01:55.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1", "trip": { "id": "7c1e4d8f-3a2b-8d5e-9f60-1b2c3d4e5f6a", "distance_m": 3120.5, "duration_seconds": 715, "install_id": "2bed7f6c-9d41-4a2f-8b7e-0a1c2d3e4f50", "last_point_at": "2026-10-07T14:01:55.000Z", "mode": "driving", "mode_counts": {"driving": 28, "walking": 1}, "point_count": 29, "revision": 4, "settings_revision": 7, "start": {"latitude": 12.9352, "longitude": 77.6245}, "started_at": "2026-10-07T13:50:00.000Z", "status": "stalled", "user_id": "acct_9931" }}| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | always | The event id (a UUIDv7). Your deduplication key. |
type | string | always | trip.started, trip.stalled or trip.ended. |
occurred_at | string | always | The trip’s own time on the device’s timeline: its started_at (started), last_point_at (stalled: the last thing the device recorded before it went quiet) or ended_at (ended). Not when the event was produced or delivered. |
detected_at | string | always | When the server produced the event, on the server’s clock. For trip.stalled, at least silence_timeout_seconds after the device’s last contact, unless the device was declared unreachable sooner. |
project_id | string | always | Your project. |
device | object | always | install_id (always) · user_id (when the trip has one). |
trip | object | always | The trip object, exactly as GET /v1/trips/{trip_id} returned it when the event was produced: status open (or closed, for a trip that arrived whole) on trip.started, stalled on trip.stalled, closed on trip.ended. |
When they fire.
trip.startedfires once, when the trip is first stored. A trip is stored at its third location, so the event arrives after the trip began:occurred_atis often minutes before you receive it.trip.stalledfires once per stall, when an open trip’s device has had no contact forsilence_timeout_seconds(default: the effectivemax_gap_seconds, 600 seconds unless you changed it), or as soon as the device is declared unreachable. A trip can stall more than once: new locations return it toopen(with no event), and a later silence stalls it again at a highertrip.revision. See the trip lifecycle.trip.endedfires exactly once, when a stored trip first becomesclosed, fromopenorstalled. It is final. A device that uploads a whole trip at once, for example after being offline, producestrip.startedandtrip.endedtogether.- A trip event is never produced twice for the same trip and type (for
trip.stalled, the same trip, type and revision), even when the server retries its work.
When trip.ended arrives, with the default settings:
| What happened | trip.stalled | trip.ended | end_reason |
|---|---|---|---|
The app called stop() | none | within seconds in in1, later in other regions | tracking_stopped |
| The device stopped, GPS kept on | none | about stop_duration_seconds after it arrived | stop |
| The device stopped and paused GPS, SDK 0.6.0 or later | none | when the SDK declares the rest | stop |
| The device stopped and paused GPS, SDK 0.5.0 or earlier | after 10 minutes without contact | at its next check-in or departure | stop |
| The app was killed, the battery died, or the app was uninstalled | after 10 minutes without contact | after finality_timeout_seconds (24 hours) | silence |
| Offline for 30 minutes while driving, then uploads | after 10 minutes without contact | when the real stop is confirmed | stop |
Offline for longer than finality_timeout_seconds while driving | after 10 minutes without contact | after finality_timeout_seconds | silence; the rest of the journey becomes a new trip |
Rules for your integration.
trip.endedis final for its trip id. Delivery is unordered, so atrip.stalledcan arrive after it: ignore atrip.stalledfor a trip you have already seen end.- Between two
trip.stalledevents for one trip, the highertrip.revisionwins. - Subscribe to
trip.stalledonly if you can act on “probably ended” and reconcile whentrip.endedbrings the real end. An endpoint that takes onlytrip.endedis never handed a guess. Choose with the endpoint’sevent_types. - A
trip.endedcan come without atrip.started. A trip that was already open when trip events were switched on in its region (see the changelog) ends without a start. So can a trip whose id a rebuild changed. Atrip.endedcan also be delivered before itstrip.started. - The
tripmember is a snapshot. It does not change after the event is produced. ReadGET /v1/trips/{trip_id}for the trip as it is now. - Some changes send nothing. A return from
stalledtoopensends nothing, and neither does a late location that changes a closed trip, a rebuild, retention or data erasure.
Device presence events
Section titled “Device presence events”The server keeps track of whether it still hears from each device running the SDK in cloud mode.
When a device that has something in progress (it is confirmed inside one of your geofences, or
has an open or stalled trip) stops being reachable, Beekon sends device.unreachable. When the
device is heard from again, it sends device.reachable.
A device on a trip whose app was killed, declared unreachable when the 12-hour rest limit passed:
{ "id": "019000ee-0000-7000-8000-0000000000a1", "type": "device.unreachable", "detected_at": "2026-06-07T02:00:41.000Z", "device": { "install_id": "9f1b6c2e-8d4a-4b7f-9c3d-2e1f0a9b8c7d", "user_id": "customer-42" }, "occurred_at": "2026-06-07T02:00:00.000Z", "presence": { "context": { "geofences": [{"id": "019000f0-0000-7000-8000-0000000000f1"}], "trip_id": "3e9a7b1c-5d2f-8a4e-9b60-7c8d9e0f1a2b" }, "last_contact_at": "2026-06-06T14:00:00.000Z", "last_fix": { "accuracy_m": 9.5, "latitude": 12.9716, "longitude": 77.5946, "recorded_at": "2026-06-06T13:59:58.000Z" }, "reason": "rest_limit" }, "project_id": "019000b0-0000-7000-8000-0000000000b1"}The device.reachable that ends the same episode:
{ "id": "019000ee-0000-7000-8000-0000000000a2", "type": "device.reachable", "detected_at": "2026-06-07T03:40:05.000Z", "device": { "install_id": "9f1b6c2e-8d4a-4b7f-9c3d-2e1f0a9b8c7d", "user_id": "customer-42" }, "occurred_at": "2026-06-07T03:40:04.000Z", "presence": { "context": {"geofences": []}, "last_contact_at": "2026-06-06T14:00:00.000Z", "last_fix": { "accuracy_m": 9.5, "latitude": 12.9716, "longitude": 77.5946, "recorded_at": "2026-06-06T13:59:58.000Z" }, "unreachable_event_id": "019000ee-0000-7000-8000-0000000000a1" }, "project_id": "019000b0-0000-7000-8000-0000000000b1"}| Field | Type | Presence | Meaning |
|---|---|---|---|
id | string | always | The event id (a UUIDv7). Your deduplication key. |
type | string | always | device.unreachable or device.reachable. |
occurred_at | string | always | On the server’s clock. device.unreachable: the deadline that passed (silent_while_moving, rest_limit), or when the server received the upload that reported the stop or the lost permission (tracking_stopped, permission_lost). device.reachable: when the server received the upload that ended the silence. |
detected_at | string | always | When the server produced the event, at or after occurred_at. For a deadline, the difference is the check’s lag: normally under a minute in the in1 region, and later in other regions. |
project_id | string | always | The project of the device’s last accepted upload. |
device | object | always | install_id (always) · user_id (when the device’s newest admitted location carried one). |
presence.reason | string | device.unreachable only | Why the device is unreachable (table below). Read a value you don’t know as “unreachable, reason unknown”. |
presence.probe_unanswered | boolean | only as true, device.unreachable only | The server sent the device a push probe during this silence and no answer arrived. Not produced until the probe is on: see the push probe. |
presence.last_contact_at | string | always | When the server last received an upload from the device before the silence. On device.reachable it repeats the device.unreachable’s value, so last_contact_at and occurred_at bound the silent window. |
presence.last_fix | object | when the device ever sent a location | The device’s newest admitted location: latitude, longitude, recorded_at, and accuracy_m when it had an accuracy. |
presence.context | object | always | What the device had in progress when the event was produced: geofences (always; every fence it is confirmed inside, as {id}, in ascending id order, possibly empty; as in geofence events, an external_id member is reserved for fences authored with one, which no endpoint offers yet) and trip_id (when it has an open or stalled trip). |
presence.unreachable_event_id | string | device.reachable only | The id of the device.unreachable that opened this episode. |
reason | When |
|---|---|
silent_while_moving | A moving device sent nothing past its deadline. |
rest_limit | A resting device sent nothing for longer than the project’s presence.rest_limit_seconds. |
tracking_stopped | The app called stop() while the device was inside a fence or on a trip. |
permission_lost | The device reported that location permission was taken away or location was switched off. |
What counts as hearing from a device. Every upload the server accepts from the SDK on that
device counts as contact, including a heartbeat or an upload with no locations. Config
fetches, refused uploads and uploads you make with a server key through
POST /v1/ingest do not. A device whose locations reach Beekon only through
server-key uploads produces no presence events.
The deadlines. After each contact the server sets a deadline from what the device reported:
| The device is | Deadline after its last contact |
|---|---|
| Moving | Twice its upload interval, plus 120 seconds. The interval is the larger of sync.interval_seconds and the platform’s floor: 900 seconds on Android, 60 seconds on iOS. With the default 300-second interval, that is 720 seconds on iOS and 1920 seconds on Android. |
| Resting | presence.rest_limit_seconds from your remote config, 43200 seconds (12 hours) by default. |
Stopped (the app called stop()) | None: the server waits for it to start again. |
Devices on SDK 0.5.0 and earlier count as resting. A device is moving or resting by what its
SDK says. SDK 0.6.0 and later say when the device is resting, so a device on 0.6.0 that tracks
without declaring rest is moving. SDK 0.5.0 and earlier can’t say it, so those devices are treated
as resting while they track: the moving deadline and silent_while_moving don’t apply to them,
and one whose app is killed while it moves is declared unreachable only when the rest limit passes
(12 hours by default).
- A project whose
tracking.when_stationaryisreduceorkeephas every device treated as resting, whatever the SDK, because its devices may send nothing for hours by design. heartbeat_interval_secondsdoesn’t shorten the resting deadline, but each heartbeat is contact and moves the deadline forward.- The server checks deadlines every minute.
occurred_atis the deadline itself, anddetected_atshows how late the check ran: punctual in thein1region, later in other regions.
When an event is sent.
- Only for a device with something in progress. A device becomes unreachable whether or not
it has a fence visit or a trip, but the event is sent only if it is confirmed inside at least
one fence or has an open or stalled trip at that moment. Phones switched off overnight with
nothing in progress send nothing.
tracking_stoppedandpermission_lostmake such a device unreachable only when it has something in progress. - One episode, at most two events. An episode runs from the moment the device becomes
unreachable to its next contact. It produces at most one
device.unreachableand onedevice.reachable. Adevice.reachableis sent only if the episode’sdevice.unreachablewas sent, whatever the device has in progress when it returns. - Unordered. A
device.reachablecan arrive before itsdevice.unreachable. Pair them bypresence.unreachable_event_id.
What it means. A device.unreachable is a fact on the server’s clock and is never
retracted: the server heard nothing before the deadline, or the device said it can no longer
track. It says nothing about where the device is: a phone whose battery died or whose app was
force-stopped can’t be located. The server reports it unreachable when its deadline passes:
the moving deadline for a moving device on SDK 0.6.0 or later, otherwise after 12 hours by
default, and later than that outside the in1 region. What
happens to the device’s fence visits and trips is sent as separate events: a fence’s on_unreachable
policy decides whether you get a geofence.exit with evidence: unreachable, and an open trip
stalls with a trip.stalled.
The push probe
How the probe works once it is on
Before it declares a silent device unreachable, the
server can send it one push message with your app’s own push credentials and wait 120 seconds for
an answer. An answer is ordinary contact, so no event is sent. Without an answer, the
device.unreachable carries probe_unanswered: true. At most one probe is sent per device per
hour, and only for the two deadline reasons. The probe is optional and off by default; when it is
on for your project, the server sets features.presence_probe in the config devices receive, and
you cannot set that flag yourself (see
Remote config).
Usage threshold events
Section titled “Usage threshold events”{ "id": "019ecb27-2200-7000-8000-0000000000b8", "type": "billing.usage_threshold", "occurred_at": "2026-06-15T12:00:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1", "usage": { "cap_mtu": 100, "month": 6, "mtu": 85, "threshold": 80, "year": 2026 }}| Field | Type | Meaning |
|---|---|---|
id | string | The event id; one per project, month and threshold, ever. |
type | string | billing.usage_threshold. |
occurred_at | string | When the month’s count crossed the threshold. |
project_id | string | Your project. |
usage | object | cap_mtu (your monthly active user cap) · mtu (the monthly active user count at the crossing) · threshold (50, 80 or 100, percent of the cap) · month (1–12) · year. All integers. |
A usage event has no device, geofence, location or detected_at. Each threshold fires at
most once per calendar month (UTC); raising your cap does not re-arm a threshold already crossed
that month. The events are the cap’s alert, not a stop: after the 100% event, new users are still
admitted and counted. See the MAU cap.
Ping events
Section titled “Ping events”{ "id": "01a1150d-fa40-7c2d-8e3f-405162738495", "type": "webhook.ping", "occurred_at": "2026-10-07T06:30:00.000Z", "project_id": "019000b0-0000-7000-8000-0000000000b1"}A webhook.ping has only id, type, occurred_at (when the ping was made) and project_id.
It reaches only the webhook endpoint that was pinged, is never retried, and never appears in
GET /v1/events. Acknowledge it with a 2xx like any delivery.
Ordering and duplicates
Section titled “Ordering and duplicates”- Events carry no ordering guarantee relative to each other, per device or per fence. If you
need order, sort by
occurred_atand tolerate late arrivals. - The same event can reach you more than once: through redelivered webhooks, or through both a
webhook and this feed. Deduplicate on
id, atomically (a unique index or upsert), not by read-then-write.
Next: receive these events as they happen with a webhook.