Telemetry / API reference

Fleet locations

Read the latest stored location for every asset in an authorized connection.

GET/v1/connections/{id}/locations

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

Returns up to 100 roster assets per page, including assets without a location. Pass nextCursor as after until it is null.
retrieval:stored means this reads our database. It does not make a live provider request. Use each location's observedAt and fetchedAt to assess freshness; available, stale and missing have the same meanings as Current readings.
Latitude and longitude are decimal degrees. A zero coordinate is valid. Missing location returns reading:null rather than a zero coordinate.
A current roster is not a point-in-time snapshot across pages. Insertions or removals during pagination may require another pass.
For current provider data, the existing per-asset refresh is available. A separate fleet-wide live location operation is still a parity gap.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`after`	query	No	`string` Opaque provider vehicle ID from nextCursor. Keep the same time window when paging.

Request example

bash

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

Response fields

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

Field	Type	Required
`locations`	`object[]`	Yes
`nextCursor`	`string \| null`	Yes
`retrieval`	`"stored"`	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

{
  "locations": [
    {
      "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"
        }
      }
    }
  ],
  "nextCursor": null,
  "retrieval": "stored"
}

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": {
    "locations": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "vehicleId": {
            "type": "string"
          },
          "location": {
            "$ref": "#/components/schemas/locationStatus"
          }
        },
        "required": [
          "vehicleId",
          "location"
        ]
      }
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "retrieval": {
      "type": "string",
      "const": "stored"
    }
  },
  "required": [
    "locations",
    "nextCursor",
    "retrieval"
  ]
}

← API overview · Download OpenAPI