Trips / API reference

Get trip

Read one current authorized trip by its stable trp_ ID.

GET/v1/connections/{id}/trips/{tripId}

Authentication: Bearer consumer API key with an explicit connection grant.

Preview contract. Availability depends on the deployed release, authorized connection and asset.

How to use this endpoint

Uses the same permissions, milliseconds/kilometres and independently authorized driver/vehicle expansion as List historical trips. No current completed history returns409; an inaccessible/missing trip returns404.
Raw/deletion access remains unavailable (409). expand=vehicle returns the current visible vehicle resource when independently authorized; otherwise the stable ID remains. Expanded vehicle groups are shared IDs with independent permissions and explicit groupMembership availability; group objects are not nested. IDs persist across same-account recollection, while renewal hides old consent rows until recollection. Reading this endpoint does not activate source collection.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`tripId`	path	Yes	`TripId`
`expand`	query	No	`driver \| vehicle \| driver,vehicle \| vehicle,driver` Expand current independently authorized stored driver/vehicle profiles. Missing, unauthorized or filter-hidden vehicle profiles retain the normalized vehicle ID; expansion grants no new access. Expanded vehicles contain the same current permissioned directory group IDs/availability as direct vehicle reads. This is one-level expansion; group objects are not nested here.
`raw`	query	No	`boolean` true returns409: original raw access and physical deletion evidence are not implemented. Default: `false`
`deleted`	query	No	`boolean` true returns409: original raw access and physical deletion evidence are not implemented. Default: `false`

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/trips/$TRIP_ID" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

HTTP 200 returns Trip. Fields listed as required are guaranteed by this contract; optional fields may be absent.

Field	Type	Required
`id`	`TripId`	Yes
`sourceId`	`string`	Yes
`provider`	`samsara \| motive \| geotab`	Yes
`vehicle`	`TripVehicleId \| ExpandedVehicle`	Yes
`driver`	`DriverId \| TripDriver`	No
`startedAt`	`string`	Yes
`endedAt`	`string`	Yes
`duration`	`number`	Yes
`distance`	`number`	No
`startLocation`	`object`	No
`endLocation`	`object`	No
`metadata`	`object`	Yes

Nested field shapes and constraints are defined in the OpenAPI contract. For latest telemetry values, see normalized units and availability.

Response example

Synthetic values; this is a shape example, not a live customer response.

json

{
  "id": "trp_01D9ZQFGHVJ858NBF2Q7DV9MNH",
  "sourceId": "trip-001",
  "provider": "geotab",
  "vehicle": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "startedAt": "2026-10-01T00:00:00Z",
  "endedAt": "2026-10-01T00:20:00Z",
  "duration": 1200000,
  "distance": 1.609344,
  "metadata": {
    "addedAt": "2026-10-01T00:00:00Z",
    "modifiedAt": "2026-10-01T00:00:00Z"
  }
}

Errors and retries

HTTP status	Meaning
`400`	Invalid time window, metric or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`409`	Requested raw/deletion unavailable, or trip detail pending
`413`	Trip response exceeds4MiB; lower limit or omit expansion
`503`	Service or database unavailable

Errors return {"error":"reason_code"}. Honor Retry-After when a 429 includes it. Permission and provider failures never become zero-valued telemetry. Connection health and reading status provide separate signals.

Response schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "$ref": "#/components/schemas/TripId"
    },
    "sourceId": {
      "type": "string"
    },
    "provider": {
      "type": "string",
      "enum": [
        "samsara",
        "motive",
        "geotab"
      ]
    },
    "vehicle": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/TripVehicleId"
        },
        {
          "$ref": "#/components/schemas/ExpandedVehicle"
        }
      ]
    },
    "driver": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/DriverId"
        },
        {
          "$ref": "#/components/schemas/TripDriver"
        }
      ]
    },
    "startedAt": {
      "type": "string",
      "format": "date-time"
    },
    "endedAt": {
      "type": "string",
      "format": "date-time"
    },
    "duration": {
      "type": "number",
      "minimum": 0,
      "description": "Milliseconds of source-reported driving duration or elapsed motion interval; see Units."
    },
    "distance": {
      "type": "number",
      "minimum": 0,
      "description": "Kilometres; omitted when missing/invalid. GPS distance and odometer difference remain distinct source bases."
    },
    "startLocation": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "required": [
        "latitude",
        "longitude"
      ]
    },
    "endLocation": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "required": [
        "latitude",
        "longitude"
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "addedAt": {
          "type": "string",
          "format": "date-time"
        },
        "modifiedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "addedAt",
        "modifiedAt"
      ]
    }
  },
  "required": [
    "id",
    "sourceId",
    "provider",
    "vehicle",
    "startedAt",
    "endedAt",
    "duration",
    "metadata"
  ]
}

← API overview · Download OpenAPI