Telemetry / API reference

Current readings

Get the latest location, odometer, engine runtime and other normalized readings for an asset.

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

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

Read odometer.reading.value.meters for the lifetime distance meter; engineHours.reading.value.seconds for lifetime engine runtime; location.reading.value for latitude/longitude.
Each field has available, stale or missing status. Missing returns reading:null. Zero is a valid observed value.
This reads stored data; use refresh to request a provider read. A recent collection does not guarantee a new hardware sample.
The API already converts distance to meters and duration to seconds. Do not apply reading.units.factor to the normalized value again.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`vehicleId`	path	Yes	`string`

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/vehicles/$VEHICLE_ID/telemetry" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`vehicleId`	`string`	Yes
`location`	`locationStatus`	Yes
`odometer`	`odometerStatus`	Yes
`engineHours`	`engineHoursStatus`	No
`totalIdleTime`	`totalIdleTimeStatus`	No
`speed`	`speedStatus`	No
`heading`	`headingStatus`	No
`fuelPercent`	`fuelPercentStatus`	No
`batteryVoltage`	`batteryVoltageStatus`	No
`engineState`	`engineStateStatus`	No
`faultsObservedAt`	`string \| null`	No
`refreshStatus`	`fetched \| no_new_odometer \| failed`	No

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",
  "location": {
    "status": "available",
    "reading": {
      "value": {
        "latitude": 0,
        "longitude": 0
      },
      "source": "example:position",
      "observedAt": "2026-10-01T00:00:00Z",
      "fetchedAt": "2026-10-01T00:00:00Z"
    }
  },
  "odometer": {
    "status": "available",
    "reading": {
      "value": {
        "meters": 160934.4
      },
      "source": "example:odometer",
      "observedAt": "2026-10-01T00:00:00Z",
      "fetchedAt": "2026-10-01T00:00:00Z",
      "units": {
        "source": "miles",
        "normalized": "meters",
        "factor": 1609.344
      }
    }
  },
  "engineHours": {
    "status": "available",
    "reading": {
      "value": {
        "seconds": 720000
      },
      "source": "example:engine-counter",
      "observedAt": "2026-10-01T00:00:00Z",
      "fetchedAt": "2026-10-01T00:00:00Z",
      "units": {
        "source": "hours",
        "normalized": "seconds",
        "factor": 3600
      }
    }
  },
  "totalIdleTime": {
    "status": "missing",
    "reading": null
  },
  "speed": {
    "status": "missing",
    "reading": null
  },
  "heading": {
    "status": "missing",
    "reading": null
  },
  "fuelPercent": {
    "status": "missing",
    "reading": null
  },
  "batteryVoltage": {
    "status": "missing",
    "reading": null
  },
  "engineState": {
    "status": "missing",
    "reading": null
  },
  "faultsObservedAt": "2026-10-01T00:00:00Z"
}

Errors and retries

HTTP status	Meaning
`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"
    },
    "location": {
      "$ref": "#/components/schemas/locationStatus"
    },
    "odometer": {
      "$ref": "#/components/schemas/odometerStatus"
    },
    "engineHours": {
      "$ref": "#/components/schemas/engineHoursStatus"
    },
    "totalIdleTime": {
      "$ref": "#/components/schemas/totalIdleTimeStatus"
    },
    "speed": {
      "$ref": "#/components/schemas/speedStatus"
    },
    "heading": {
      "$ref": "#/components/schemas/headingStatus"
    },
    "fuelPercent": {
      "$ref": "#/components/schemas/fuelPercentStatus"
    },
    "batteryVoltage": {
      "$ref": "#/components/schemas/batteryVoltageStatus"
    },
    "engineState": {
      "$ref": "#/components/schemas/engineStateStatus"
    },
    "faultsObservedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "refreshStatus": {
      "type": "string",
      "enum": [
        "fetched",
        "no_new_odometer",
        "failed"
      ]
    }
  },
  "required": [
    "vehicleId",
    "location",
    "odometer"
  ]
}

← API overview · Download OpenAPI