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 thensfilterquery parameter. Thensfiltervalue must name only namespaces the class's ontology belongs to. Otherwise, the service returns404. Writes needINDIVIDUALS_CREATEon the class, and reads needINDIVIDUALS_READ. For more information, see Permissions.
This section contains the following API calls:
- Add readings to an individual
- Add readings to several individuals
- Get the readings of an individual
- Get the readings of a class
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
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the class | Required |
individualId | String | The ID of the telemetry individual | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
sourceId | String | The source device ID to set on every reading. A reading that carries a different _sourceId returns 400. | Optional |
transactional | Boolean | If 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.
| Parameter | Type | Description | Required |
|---|---|---|---|
_ts | String | The ISO 8601 time of the measurement | Required |
_tsMetadata._telItemId | String | The ID of the telemetry individual. If you send it, it must match individualId. | Optional |
_tsMetadata._sourceId | String | The source device ID. Required unless you send the sourceId query parameter. | Optional |
| Any other field | Any | The measured values | Optional |
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
| Code | Description |
|---|---|
204 | No Content |
400 | Bad 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. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_CREATE grant, or the Item Service refused the call. |
404 | Not Found. The class is not in the live version or has no live mapping, or individualId isn't a valid individual ID. |
409 | Conflict. The ontology has no live version, or the class's live mapping has no collection yet. |
413 | The batch has more readings than the maximum, 2000 by default |
502 | Bad 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
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
transactional | Boolean | If 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.
| Parameter | Type | Description | Required |
|---|---|---|---|
_ts | String | The ISO 8601 time of the measurement | Required |
_tsMetadata._telItemId | String | The ID of the telemetry individual | Required |
_tsMetadata._sourceId | String | The source device ID | Required |
| Any other field | Any | The measured values | Optional |
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
| Code | Description |
|---|---|
204 | No Content |
400 | Bad 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. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_CREATE grant, or the Item Service refused the call. |
404 | The class is not in the live version, or it has no live mapping |
409 | Conflict. The ontology has no live version, or the class's live mapping has no collection yet. |
413 | The batch has more readings than the maximum, 2000 by default |
502 | Bad 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
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the class | Required |
individualId | String | The ID of the telemetry individual | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
from | String | The earliest _ts to return, inclusive, in ISO 8601 | Optional |
to | String | The latest _ts to return, exclusive, in ISO 8601 | Optional |
offset | Integer | The number of readings to skip. Default is 0. | Optional |
limit | Integer | The page size. Default is 200. A value above the maximum page size, 1000 by default, returns 400. | Optional |
ascending | Boolean | If 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
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. limit is above the maximum page size, or the class is not bound to a NamedTelemetryCollection. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | Not 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. |
409 | Conflict. The ontology has no live version, or the class's live mapping has no collection yet. |
502 | Bad 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
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the class | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | Namespace filter to apply | Required |
from | String | The earliest _ts to return, inclusive, in ISO 8601 | Optional |
to | String | The latest _ts to return, exclusive, in ISO 8601 | Optional |
offset | Integer | The number of readings to skip. Default is 0. | Optional |
limit | Integer | The page size. Default is 200. A value above the maximum page size, 1000 by default, returns 400. | Optional |
ascending | Boolean | If 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
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. limit is above the maximum page size, or the class is not bound to a NamedTelemetryCollection. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | The class is not in the live version, or it has no live mapping |
409 | Conflict. 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. |
502 | Bad Gateway. The Item Service failed or was unreachable. |