Usage / API reference

Asset utilization

Measure how much an asset's engine ran versus did not run during observed time.

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

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

Requires a time window of at most seven days. Boundary samples at startTime and endTime can be counted.
Engine runtime includes idle and PTO. This measures engine activity, not productive work, job availability or scheduled work hours.
Inspect coverageSeconds and coveragePercent for each metric. Unobserved time is unknown, never unused time.
Only nondecreasing same-source counter pairs at most 30 minutes apart count. Resets, source changes (including A → B → A), implausible jumps and longer gaps are excluded.
More than 10,000 counter readings returns 413. Incomplete database evidence returns 503. Narrow the window; no partial result is silently labeled complete.

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.

Request example

bash

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

Response fields

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

Field	Type	Required
`vehicleId`	`string`	Yes
`window`	`Window`	Yes
`definition`	`"engine_runtime_over_observed_time_v1"`	Yes
`maxObservationGapSeconds`	`1800`	No
`engineRuntime`	`Counter`	Yes
`engineNotRunning`	`Counter`	Yes
`engineOnPercentOfObservedTime`	`number \| null`	Yes
`distance`	`Counter`	Yes
`idleTime`	`Counter`	Yes
`limitations`	`string[]`	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",
  "window": {
    "startTime": "2026-10-01T00:00:00Z",
    "endTime": "2026-10-01T00:20:00Z"
  },
  "definition": "engine_runtime_over_observed_time_v1",
  "maxObservationGapSeconds": 1800,
  "engineRuntime": {
    "status": "complete",
    "value": 300,
    "coverageSeconds": 1200,
    "coveragePercent": 100,
    "sampleCount": 2,
    "excludedIntervals": 0,
    "sources": [
      "example:engine-counter"
    ],
    "intervals": [
      {
        "startTime": "2026-10-01T00:00:00Z",
        "endTime": "2026-10-01T00:20:00Z",
        "amount": 300
      }
    ],
    "unit": "seconds"
  },
  "engineNotRunning": {
    "status": "complete",
    "value": 900,
    "unit": "seconds",
    "coverageSeconds": 1200
  },
  "engineOnPercentOfObservedTime": 25,
  "distance": {
    "status": "missing",
    "value": null,
    "coverageSeconds": 0,
    "coveragePercent": 0,
    "sampleCount": 0,
    "excludedIntervals": 0,
    "sources": [],
    "intervals": [],
    "unit": "meters"
  },
  "idleTime": {
    "status": "missing",
    "value": null,
    "coverageSeconds": 0,
    "coveragePercent": 0,
    "sampleCount": 0,
    "excludedIntervals": 0,
    "sources": [],
    "intervals": [],
    "unit": "seconds"
  },
  "limitations": [
    "Runtime includes idling and PTO; it is not productive work or availability utilization.",
    "Only same-source counter pairs within 30 minutes are counted. Resets, source changes and larger gaps are excluded.",
    "Unobserved time is unknown. No interpolation or backfill is assumed."
  ]
}

Errors and retries

HTTP status	Meaning
`400`	Invalid time window, metric or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`413`	Requested utilization has more than 10,000 readings; narrow the window
`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"
    },
    "definition": {
      "const": "engine_runtime_over_observed_time_v1"
    },
    "maxObservationGapSeconds": {
      "const": 1800
    },
    "engineRuntime": {
      "$ref": "#/components/schemas/Counter"
    },
    "engineNotRunning": {
      "$ref": "#/components/schemas/Counter"
    },
    "engineOnPercentOfObservedTime": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 100
    },
    "distance": {
      "$ref": "#/components/schemas/Counter"
    },
    "idleTime": {
      "$ref": "#/components/schemas/Counter"
    },
    "limitations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "vehicleId",
    "window",
    "definition",
    "engineRuntime",
    "engineNotRunning",
    "distance",
    "idleTime",
    "engineOnPercentOfObservedTime"
  ]
}

← API overview · Download OpenAPI