Faults / API reference

Fault events

Read opened and cleared transitions for service-case triggers and incremental syncing.

GET/v1/connections/{id}/fault-events

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

Start with after=0 or your saved cursor. Process each event, persist its deduplication key and checkpoint, then request nextCursor.
Use hasMore to drain pages. When false, retain nextCursor for the next poll; it may equal the cursor you sent when there are no new events.
An opened event marked bootstrap is initial evidence. Decide whether your product should create a case for it; the service does not create cases.
Use the event/occurrence IDs for replay-safe processing. Provider code alone is not a unique event ID.

Parameters

Name Where Required Type and behavior

id path Yes string

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`after`	query	No	`string` Opaque sequence cursor. History pages follow ingestion order, not source-time order. Keep all filters fixed. Default: `0`

after

query

string

Opaque sequence cursor. History pages follow ingestion order, not source-time order. Keep all filters fixed.

Default: 0

Request example

bash

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

Response fields

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

Field	Type	Required
`events`	`FaultEvent[]`	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

{
  "events": [
    {
      "sequence": "1",
      "id": "30000000-0000-4000-8000-000000000003",
      "connection_id": "10000000-0000-4000-8000-000000000001",
      "occurrence_id": "20000000-0000-4000-8000-000000000002",
      "vehicle_id": "asset-001",
      "kind": "opened",
      "observed_at": "2026-10-01T00:00:00Z",
      "bootstrap": false
    }
  ],
  "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": {
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FaultEvent"
      }
    },
    "nextCursor": {
      "type": "string"
    },
    "hasMore": {
      "type": "boolean"
    }
  },
  "required": [
    "events",
    "nextCursor",
    "hasMore"
  ]
}

← API overview · Download OpenAPI