Telemetry / API reference

Telemetry history

Read stored normalized observations for an asset and time window.

GET/v1/connections/{id}/vehicles/{vehicleId}/history

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

startTime is inclusive; endTime is exclusive. Both require RFC3339 timestamps with an offset; the window is at most 31 days and cannot end in the future.
Use metric to select a field, such as odometer or engineHours. Omit it to retrieve all stored metrics.
Returns 100 readings per page in ingestion sequence, not observation-time order. Keep filters fixed and pass nextCursor as after while hasMore is true.
History starts after collection with history support is activated. No automatic backfill or import of older provider data is included.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`vehicleId`	path	Yes	`string`
`startTime`	query	Yes	`string` RFC3339 with offset. History: inclusive; counters use only samples within the window. No interpolation.
`endTime`	query	Yes	`string` After startTime and no later than now. History: exclusive. Counter summaries permit a boundary sample at endTime.
`after`	query	No	`string` Opaque sequence cursor. History pages follow ingestion order, not source-time order. Keep all filters fixed. Default: `0`
`metric`	query	No	`location \| odometer \| engineHours \| totalIdleTime \| speed \| heading \| fuelPercent \| batteryVoltage \| engineState` Optional history field filter.

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/vehicles/$VEHICLE_ID/history?startTime=2026-10-01T00:00:00Z&endTime=2026-10-01T00:20:00Z&metric=odometer" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`vehicleId`	`string`	Yes
`window`	`Window`	Yes
`readings`	`HistoryPoint[]`	Yes
`nextCursor`	`string`	Yes
`hasMore`	`boolean`	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

{
  "vehicleId": "asset-001",
  "window": {
    "startTime": "2026-10-01T00:00:00Z",
    "endTime": "2026-10-01T00:20:00Z"
  },
  "readings": [
    {
      "sequence": "1",
      "metric": "odometer",
      "source": "example:odometer",
      "observed_at": "2026-10-01T00:00:00Z",
      "fetched_at": "2026-10-01T00:00:00Z",
      "value": {
        "meters": 160934.4
      },
      "units": {
        "source": "miles",
        "normalized": "meters",
        "factor": 1609.344
      }
    }
  ],
  "nextCursor": "1",
  "hasMore": false
}

Errors and retries

HTTP status	Meaning
`400`	Invalid time window, metric or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`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",
  "properties": {
    "vehicleId": {
      "type": "string"
    },
    "window": {
      "$ref": "#/components/schemas/Window"
    },
    "readings": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/HistoryPoint"
      }
    },
    "nextCursor": {
      "type": "string"
    },
    "hasMore": {
      "type": "boolean"
    }
  },
  "required": [
    "vehicleId",
    "window",
    "readings",
    "nextCursor",
    "hasMore"
  ]
}

← API overview · Download OpenAPI