Telemetry / API reference

Refresh current readings

Request current asset readings, then return the same normalized telemetry shape.

POST/v1/connections/{id}/vehicles/{vehicleId}/refresh

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

Send no JSON request body. Refresh is limited to once per asset every 30 seconds; a 429 includes Retry-After.
refreshStatus is fetched, no_new_odometer or failed. fetched means an odometer was returned; inspect observedAt to determine freshness.
A failed provider read can still return HTTP 200 with refreshStatus:failed, an explicitly stale/fallback odometer, and the stored readings.
This cannot force hardware to generate a new sample. Optional-field failures are separate from core odometer/location health.

Parameters

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

No JSON request body is required.

Request example

bash

curl --request POST "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/vehicles/$VEHICLE_ID/refresh" \
  --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",
  "refreshStatus": "fetched"
}

Errors and retries

HTTP status	Meaning
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`429`	Refresh or session rate limit; inspect Retry-After
`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