Skip to main content
Version: v5.3

Telemetry readings

A reading is a time-stamped measurement recorded against an individual of a telemetry class. The service stores readings in the time series of the class's NamedTelemetryCollection. These endpoints suit simulators, corrections, and agents. For bulk telemetry, use the Item Service ingestion routes instead. For more information, see Telemetry readings.

Readings always use the live version of the ontology, so X-Ontology-Draft has no effect. The class's live mapping must point at a NamedTelemetryCollection. The /classes/{classId}/individuals/readings route accepts only GET and POST. Other methods return 405.

Note: Every request needs an Authorization: Bearer <token> header and the nsfilter query parameter. The nsfilter value must name only namespaces the class's ontology belongs to. Otherwise, the service returns 404. Writes need INDIVIDUALS_CREATE on the class, and reads need INDIVIDUALS_READ. For more information, see Permissions.

This section contains the following API calls:

Add readings to an individual​

Adds readings to one telemetry individual. The service sets each reading's _tsMetadata._telItemId from the path, and its _tsMetadata._sourceId from the sourceId query parameter when you send it.

Endpoints​

POST /aosvc/api/v1/classes/{classId}/individuals/{individualId}/readings

Parameters​

Path​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired
individualIdStringThe ID of the telemetry individualRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
sourceIdStringThe source device ID to set on every reading. A reading that carries a different _sourceId returns 400.Optional
transactionalBooleanIf true, the Item Service stores the batch whole or not at all. Default is false.Optional

Body​

A reading object, or an array of up to 2000 readings.

ParameterTypeDescriptionRequired
_tsStringThe ISO 8601 time of the measurementRequired
_tsMetadata._telItemIdStringThe ID of the telemetry individual. If you send it, it must match individualId.Optional
_tsMetadata._sourceIdStringThe source device ID. Required unless you send the sourceId query parameter.Optional
Any other fieldAnyThe measured valuesOptional

Example:

[
{
"_ts": "2026-10-03T00:00:00Z",
"flowRate": 42.1
},
{
"_ts": "2026-10-03T00:01:00Z",
"flowRate": 42.4
}
]

Response​

The response has no body. A 204 doesn't confirm that every reading was stored: the Item Service drops readings whose _telItemId is not an individual in the collection. To confirm, read the series back.

Codes​

CodeDescription
204No Content
400Bad Request. The body is empty or not an object or array, a reading is missing _ts or _sourceId, a reading contradicts the path or sourceId, no reading matches an individual of the class, or the class is not bound to a NamedTelemetryCollection.
401Unauthorized
403Forbidden. No INDIVIDUALS_CREATE grant, or the Item Service refused the call.
404Not Found. The class is not in the live version or has no live mapping, or individualId isn't a valid individual ID.
409Conflict. The ontology has no live version, or the class's live mapping has no collection yet.
413The batch has more readings than the maximum, 2000 by default
502Bad Gateway. The Item Service failed or was unreachable.

Add readings to several individuals​

Adds readings to several telemetry individuals of a class. Every reading carries its own _tsMetadata._telItemId and _tsMetadata._sourceId.

Endpoints​

POST /aosvc/api/v1/classes/{classId}/individuals/readings

Parameters​

Path​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
transactionalBooleanIf true, the Item Service stores the batch whole or not at all. Default is false.Optional

Body​

A reading object, or an array of up to 2000 readings.

ParameterTypeDescriptionRequired
_tsStringThe ISO 8601 time of the measurementRequired
_tsMetadata._telItemIdStringThe ID of the telemetry individualRequired
_tsMetadata._sourceIdStringThe source device IDRequired
Any other fieldAnyThe measured valuesOptional

Example:

[
{
"_ts": "2026-10-03T00:00:00Z",
"_tsMetadata": {
"_telItemId": "66f2a1c9e4b0a37d5c8e9f01",
"_sourceId": "pump-17"
},
"flowRate": 42.1
},
{
"_ts": "2026-10-03T00:00:00Z",
"_tsMetadata": {
"_telItemId": "66f2a1c9e4b0a37d5c8e9f02",
"_sourceId": "pump-18"
},
"flowRate": 17.9
}
]

Response​

The response has no body. A 204 doesn't confirm that every reading was stored: the Item Service drops readings whose _telItemId is not an individual in the collection. To confirm, read the series back.

Codes​

CodeDescription
204No Content
400Bad Request. The body is empty or not an object or array, a reading is missing _ts, _telItemId, or _sourceId, no reading matches an individual of the class, or the class is not bound to a NamedTelemetryCollection.
401Unauthorized
403Forbidden. No INDIVIDUALS_CREATE grant, or the Item Service refused the call.
404The class is not in the live version, or it has no live mapping
409Conflict. The ontology has no live version, or the class's live mapping has no collection yet.
413The batch has more readings than the maximum, 2000 by default
502Bad Gateway. The Item Service failed or was unreachable.

Get the readings of an individual​

Gets a page of the readings of one telemetry individual, newest first by default. If the class doesn't share its collection, the service doesn't check that the individual exists. An ID with no readings returns 200 with an empty _list. To check that an individual exists, use Get an individual.

Endpoints​

GET /aosvc/api/v1/classes/{classId}/individuals/{individualId}/readings

Parameters​

Path​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired
individualIdStringThe ID of the telemetry individualRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
fromStringThe earliest _ts to return, inclusive, in ISO 8601Optional
toStringThe latest _ts to return, exclusive, in ISO 8601Optional
offsetIntegerThe number of readings to skip. Default is 0.Optional
limitIntegerThe page size. Default is 200. A value above the maximum page size, 1000 by default, returns 400.Optional
ascendingBooleanIf true, sorts oldest first. Default is false.Optional

Response​

_total is the number of readings that match, not the page size.

{
"_list": [
{
"_ts": "2026-10-03T00:01:00Z",
"_tsMetadata": {
"_telItemId": "66f2a1c9e4b0a37d5c8e9f01",
"_sourceId": "pump-17"
},
"flowRate": 42.4
},
{
"_ts": "2026-10-03T00:00:00Z",
"_tsMetadata": {
"_telItemId": "66f2a1c9e4b0a37d5c8e9f01",
"_sourceId": "pump-17"
},
"flowRate": 42.1
}
],
"_total": 2,
"_offset": 0
}

Codes​

CodeDescription
200Success
400Bad Request. limit is above the maximum page size, or the class is not bound to a NamedTelemetryCollection.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404Not Found. The class is not in the live version or has no live mapping, individualId isn't a valid individual ID, or the individual belongs to another class that shares the collection.
409Conflict. The ontology has no live version, or the class's live mapping has no collection yet.
502Bad Gateway. The Item Service failed or was unreachable.

Get the readings of a class​

Gets a page of the readings of all telemetry individuals of a class, newest first by default. If several classes share the collection, the service returns only this class's readings. In that case, a class with more than 1000 individuals returns 409, so read each individual instead.

Endpoints​

GET /aosvc/api/v1/classes/{classId}/individuals/readings

Parameters​

Path​

ParameterTypeDescriptionRequired
classIdStringThe ID of the classRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
fromStringThe earliest _ts to return, inclusive, in ISO 8601Optional
toStringThe latest _ts to return, exclusive, in ISO 8601Optional
offsetIntegerThe number of readings to skip. Default is 0.Optional
limitIntegerThe page size. Default is 200. A value above the maximum page size, 1000 by default, returns 400.Optional
ascendingBooleanIf true, sorts oldest first. Default is false.Optional

Response​

_total is the number of readings that match, not the page size.

{
"_list": [
{
"_ts": "2026-10-03T00:00:00Z",
"_tsMetadata": {
"_telItemId": "66f2a1c9e4b0a37d5c8e9f02",
"_sourceId": "pump-18"
},
"flowRate": 17.9
},
{
"_ts": "2026-10-03T00:00:00Z",
"_tsMetadata": {
"_telItemId": "66f2a1c9e4b0a37d5c8e9f01",
"_sourceId": "pump-17"
},
"flowRate": 42.1
}
],
"_total": 2,
"_offset": 0
}

Codes​

CodeDescription
200Success
400Bad Request. limit is above the maximum page size, or the class is not bound to a NamedTelemetryCollection.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404The class is not in the live version, or it has no live mapping
409Conflict. The ontology has no live version, the class's live mapping has no collection yet, or the collection is shared and the class has more than 1000 individuals.
502Bad Gateway. The Item Service failed or was unreachable.