Trips / API reference

List historical trips

Read stored completed trips through one API with normalized vehicle/driver references.

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

• Stored trip reads are implemented. Availability depends on the connection's approved vehicles/start window, current trip-purpose consent, independent consumer trip read grant and completed collection. Reads never call suppliers; an implemented endpoint does not imply every fleet/provider is activated.
• duration is milliseconds; distance is kilometres. Internal storage uses seconds/metres with source provenance. Driving duration versus elapsed motion and GPS distance versus odometer difference remain different source bases. Missing/invalid coordinates or distance are omitted; zero remains valid.
• Use next as cursor with unchanged time/ID/expansion filters. Bounds are exclusive with up to6 fractional digits. Filter at most50 unique normalized vehicleIds (vcl_) or driverIds (drv_); source IDs are not normalized IDs. Publication and conservative consent/driver grant/snapshot/relationship changes expire cursors (410). Consumer-key-bound cursors cannot be transferred.
• Driver references/expand=driver require current matching-account trip/driver consent, the same driver's current stored snapshot, and the consumer's independent driver read grant. Unresolved or unauthorized driver references are omitted; filters cannot probe them. Nested group expansion is not implied by driver consent.
• Vehicle references are stable for the connection/verified account/source vehicle and are created from authorized published trips. Add expand=vehicle for a current independently approved, visible vehicle profile. Without a matching current profile grant/account, the reference stays an ID. Expanded vehicles include shared directory group IDs only when current profile, membership and directory permissions/account proof match; groupMembership reports available, not_authorized, pending, missing, invalid, partial, stale or degraded evidence. This remains one-level expansion: group objects and dotted expansion paths are unavailable. Raw/deleted true returns 409.
• Pending is distinct from a completed empty unit. coverage.completedUnits counts committed units including repeated windows; it is not a fleet-wide completeness or freshness guarantee. Provider enumeration is not transactional, and absence is not deletion. Failed collection preserves last-good trips as degraded. Backfill and recurring refresh use independently approved collection plans; scheduling does not grant new vehicles, times or driver identities. Coverage counts committed work, including repeated overlap, and is not a fleet completeness promise. Inspect status, publishedAt and coverage for this connection's actual collection state.
• metadata.modifiedAt includes a conservative shared relationship clock: permission/driver changes may surface all otherwise visible trips in modifiedAfter reads. It is a service-observed change time, not a provider timestamp. A start-selection window keeps a whole selected completed trip, including its later end. Responses are bounded to4MiB; lower list limit or omit driver/vehicle expansion after413.

Parameters

Request example

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

Response fields

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

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.

{
  "status": "pending",
  "retrieval": "stored",
  "results": [],
  "coverage": {
    "completedUnits": 0,
    "selection": "completed_trips_started_in_window",
    "completeness": "not_established"
  },
  "publishedAt": null,
  "errorCode": null
}

Errors and retries

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.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "available",
        "degraded"
      ]
    },
    "retrieval": {
      "type": "string",
      "const": "stored"
    },
    "results": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/components/schemas/Trip"
      }
    },
    "next": {
      "type": "string",
      "description": "Opaque current-grant/publication/relationship cursor; pass as cursor with unchanged filters."
    },
    "coverage": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "completedUnits": {
          "type": "integer",
          "minimum": 0
        },
        "selection": {
          "type": "string",
          "const": "completed_trips_started_in_window"
        },
        "completeness": {
          "type": "string",
          "const": "not_established"
        }
      },
      "required": [
        "completedUnits",
        "selection",
        "completeness"
      ]
    },
    "publishedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "errorCode": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "status",
    "retrieval",
    "results",
    "coverage",
    "publishedAt",
    "errorCode"
  ]
}

← API overview · Download OpenAPI