Assets / API reference

Get group

Read one group from the authorized stored account directory.

GET/v1/connections/{id}/groups/{groupId}

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

scope=directory is required. Use the stable normalized ID from the directory list, not a provider source ID or approved-ID snapshot ID. The account-group consent and current read grant must authorize this connection.
This request reads stored data without a provider call. A pending directory returns 409; a group outside the current published directory returns 404. An old credential/account generation cannot expose stored rows.
expand=parent expands one authorized parent level; further parent links remain IDs. metadata.parentResolution records unresolved external parents without inventing a root. Raw records remain unavailable (raw=true returns 409); deleted is unsupported on detail (400).
Check capturedAt and fetchedAt separately: enumeration is not transactional. stale means publication older than 24 hours; degraded retains a last-good record after a collection error. Absence is not physical deletion. Awaiting rollout and provider/fleet acceptance.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`groupId`	path	Yes	`string`
`scope`	query	Yes	`directory` directory reads the stored credential-visible group directory with separate account-group consent and read grant. Omit on lists for existing approved-ID scope. Required on group detail.
`raw`	query	No	`boolean` Raw supplier data is unavailable. raw=true returns 409. Default: `false`
`expand`	query	No	`parent` Expand one parent level within the same authorized stored snapshot; further parents remain IDs.

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/groups/$GROUP_ID?scope=directory" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`retrieval`	`"stored"`	Yes
`sourceScope`	`"credential_visible_directory"`	Yes
`consistency`	`"not_transactional"`	Yes
`deletionEvidence`	`"none"`	Yes
`fetchedAt`	`string \| null`	Yes
`capturedAt`	`string \| null`	Yes
`errorCode`	`string \| null`	Yes
`status`	`available \| stale \| degraded`	Yes
`data`	`GroupEntity`	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

{
  "status": "available",
  "retrieval": "stored",
  "sourceScope": "credential_visible_directory",
  "consistency": "not_transactional",
  "deletionEvidence": "none",
  "capturedAt": "2026-10-01T00:00:00Z",
  "fetchedAt": "2026-10-01T00:00:00Z",
  "errorCode": null,
  "data": {
    "id": "group_01D8ZQFGHVJ858NBF2Q7DV9MNC",
    "sourceId": "example-group",
    "provider": "samsara",
    "name": "Example group",
    "metadata": {
      "addedAt": "2026-10-01T00:00:00Z",
      "modifiedAt": "2026-10-01T00:00:00Z",
      "visibility": "visible",
      "parentResolution": "root_or_unreported"
    }
  }
}

Errors and retries

HTTP status	Meaning
`400`	Invalid group query, limit, expansion, time filter or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`409`	Raw provider data unavailable or group directory pending
`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": {
    "retrieval": {
      "type": "string",
      "const": "stored"
    },
    "sourceScope": {
      "type": "string",
      "const": "credential_visible_directory"
    },
    "consistency": {
      "type": "string",
      "const": "not_transactional"
    },
    "deletionEvidence": {
      "type": "string",
      "const": "none"
    },
    "fetchedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "capturedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "errorCode": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "available",
        "stale",
        "degraded"
      ]
    },
    "data": {
      "$ref": "#/components/schemas/GroupEntity"
    }
  },
  "required": [
    "retrieval",
    "sourceScope",
    "consistency",
    "deletionEvidence",
    "fetchedAt",
    "capturedAt",
    "errorCode",
    "status",
    "data"
  ]
}

← API overview · Download OpenAPI