# Trips

> Trips the server detects from each device's locations: the trip object, its open, stalled and closed states, when a trip ends, and the endpoints to list and read trips (trips:read).

Source: https://docs.getbeekon.com/api/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](#when-a-trip-ends)). The `trips` section of your [remote config](https://docs.getbeekon.com/api/remote-config/#trips) sets how trips are cut.

## GET `/v1/trips`

**Scope:** `trips:read` · Lists trips, [paged](https://docs.getbeekon.com/api/pagination/), ordered by `started_at`, then `id`. Open trips are included.

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

```jsonc
{"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}`

**Scope:** `trips:read` · Reads one trip.

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

### GET `/v1/trips/{trip_id}/points`

**Scope:** `trips:read` · The locations that make up the trip, in recorded order, [paged](https://docs.getbeekon.com/api/pagination/).

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

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

Keeping a copy in sync

Poll `GET /v1/trips` with a `from` a little before your last poll, and re-read a trip’s locations only when its `revision` changed.

## The trip object

```json
{
  "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](#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](#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](https://docs.getbeekon.com/api/location-mode/#mode-on-trips): `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](#rebuilds), 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

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](https://docs.getbeekon.com/api/events/#device-presence-events). | [`trip.stalled`](https://docs.getbeekon.com/api/events/#trip-events) |
| `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](#when-a-trip-ends).                                                                                     | [`trip.ended`](https://docs.getbeekon.com/api/events/#trip-events)   |

**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`](https://docs.getbeekon.com/api/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](https://docs.getbeekon.com/api/remote-config/#trips) 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

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

Beekon sends a [`trip.started`](https://docs.getbeekon.com/api/events/#trip-events) 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](https://docs.getbeekon.com/api/webhooks/), or read them from [`GET /v1/events`](https://docs.getbeekon.com/api/events/#get-v1events).

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

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