Skip to main content

Robot Metrics

APIs for retrieving KPI and telemetry metrics from robots.

Task Status Metrics​

TaskManagerConfig lists configured tasks. TaskRunStatusList reports the latest-known run for each reported task, including completed, canceled and failed runs.


List Available Metrics​

Returns the system metric types known to this Cloud deployment, plus the requested robot's configured Custom KPI names.

Endpoint​

GET /robots/metrics?robotId={robotId}

Request Headers​

{
"authorization": "bearer <access_token>"
}

Query Parameters​

  • robotId (string, optional): The unique identifier of the robot. Without it, only the system metric types are listed.

Response Example​

{
"metrics": [
{ "metricType": 1, "metricName": "Cpu" },
{ "metricType": 2, "metricName": "Ram" },
{ "metricType": 3, "metricName": "Disk" },
{ "metricType": 4, "metricName": "Battery" },
{ "metricType": 5, "metricName": "Odometry" },
{ "metricType": 6, "metricName": "Traffic" },
{ "metricType": 7, "metricName": "Storage" },
{ "metricType": 8, "metricName": "LicenseExpired" },
{ "metricType": 13, "metricName": "AgentHw" },
{ "metricType": 14, "metricName": "AgentSw" },
{ "metricType": 15, "metricName": "Recordings" },
{ "metricType": 16, "metricName": "Components" },
{ "metricType": 17, "metricName": "Configuration" },
{ "metricType": 18, "metricName": "Position" },
{ "metricType": 19, "metricName": "Network" },
{ "metricType": 20, "metricName": "License" },
{ "metricType": 21, "metricName": "Gpu" },
{ "metricType": 22, "metricName": "Devices" },
{ "metricType": 23, "metricName": "Nav2" },
{ "metricType": 24, "metricName": "RosEntity" },
{ "metricType": 25, "metricName": "Security" },
{ "metricType": 26, "metricName": "RosConfig" },
{ "metricType": 27, "metricName": "Wifi" },
{ "metricType": 28, "metricName": "Ping" },
{ "metricType": 29, "metricName": "RecordingProfileConfig" },
{ "metricType": 30, "metricName": "AgentOperationalState" },
{ "metricType": 31, "metricName": "UserKpiSettingsConfig" },
{ "metricType": 32, "metricName": "Thermal" },
{ "metricType": 33, "metricName": "ResourcesStorage" },
{ "metricType": 34, "metricName": "DockerRegistryConfig" },
{ "metricType": 35, "metricName": "NotificationSettingsConfig" },
{ "metricType": 36, "metricName": "TaskManagerConfig" },
{ "metricType": 37, "metricName": "TaskRunStatus" },
{ "metricType": 38, "metricName": "DebugSettingsConfig" },
{ "metricType": 39, "metricName": "LocalSessionInfo" },
{ "metricType": 40, "metricName": "TaskRunStatusList" },
{ "metricType": 43, "metricName": "SidecarStatus" },
{ "metricType": 44, "metricName": "RtspStreamingProfileConfig" },
{ "metricType": 45, "metricName": "RtspStreamingStatus" },
{ "metricType": 100, "metricName": "Apples" }
]
}
note

The catalog describes known metric types; listing a type does not guarantee a current value for that robot. The catalog can vary with the deployed API version. Entries with metricType: 100 use the configured Custom KPI name, so several entries can share type 100.

Metrics are identified by their numeric metricType ID, not by metricName. Pass the ID as metricId to Get Robot Metric. metricName is only a label, except for Custom KPIs (100), where it selects the KPI.

On Cloud, Get Robot Metric returns a value only for the types listed in Supported Metric Types. Every other type in this catalog always returns 404.

Common Errors​

  • 401: bearer token is missing or invalid.
  • 404: robotId was given, and the robot was not found or is not accessible to the caller.

Type 43 identifies Sidecar presence and operational state. Types 44 and 45 identify generalized on-demand RTSP profile configuration and runtime status. These are metric identities; their configuration and value availability depend on the deployment.


Get Robot Metric​

Retrieves the current value of a specific metric for a robot.

Endpoint​

GET /robots/{robotId}/metric/{metricId}?metricName={metricName}

Request Headers​

{
"authorization": "bearer <access_token>"
}

Path Parameters​

  • robotId (string): The unique identifier of the robot.
  • metricId (int): The numeric metric type ID (from the list above). Metrics are requested by ID, not by name.

Query Parameters​

  • metricName (string): Required only when metricId corresponds to a custom metric (100). Pass the custom metric name (e.g., Apples). Leave empty for system metrics.

Supported Metric Types​

Only the metric types below return a value. Any other type from List Available Metrics is accepted but always returns 404.

metricIdMetricReturned $type
1Cpu2 (DoubleMetric)
2Ram2 (DoubleMetric)
3Disk2 (DoubleMetric)
6Traffic5 (UsageMetric)
7Storage5 (UsageMetric)
8LicenseExpired6 (LicenseExpirationMetric)
14AgentSw7 (AgentSwMetric)
15Recordings10 (AgentRecordingMetric)
16Components11 (ComponentInfoMetric)
17Configuration12 (ConfigInfoMetric)
20License6 (LicenseExpirationMetric)
30AgentOperationalState8 (AgentOperationalStateMetric)
100Custom KPI (with metricName)1, 2, 3, 4 or 9, depending on the KPI value

A supported type still returns 404 when the robot has not reported a value for it.

Response​

The response contains the robot's basic data and the metric value. The metric field is polymorphic — its structure depends on the metric type, identified by the $type discriminator.

{
"basicData": {
"id": "11111111-2122-1122-2233-555555319861",
"name": "AMR-9"
},
"metric": {
"$type": 2,
"value": 54.3,
"name": "DoubleMetric"
}
}

A structured custom metric (one whose value is a message, such as a pose) is returned as a StringMetric ($type 3) whose value is the message as a JSON string:

{
"basicData": {
"id": "11111111-2122-1122-2233-555555319861",
"name": "AMR-9"
},
"metric": {
"$type": 3,
"value": "{\"position\":{\"x\":1.5,\"y\":2},\"orientation\":{\"w\":1}}",
"name": "StringMetric"
}
}

Fields whose value is zero or empty are left out of the JSON. The Fleet Custom KPI WebSocket sends the same value as a JSON object.

If the API cannot decode the message type, the metric is returned undecoded as a MessageStreamMetric ($type 13). Its value.data holds the base64-encoded protobuf message and value.dataType its type.

Common Errors​

  • 400: a Custom metric (100) was requested without a nonblank metricName.
  • 401: bearer token is missing or invalid.
  • 404: the robot was not found or is not accessible, the metric type is unknown or not in Supported Metric Types, the robot has no value for the metric, or no custom metric has that metricName.

Metric Types​

These are the value shapes a metric can have, identified by $type. $type is not the same as metricType/metricId. See Supported Metric Types for which metric returns which shape.

$typeNameValue Shape
0NoneMetric(no value)
1IntMetric{ "value": 42 }
2DoubleMetric{ "value": 54.3 }
3StringMetric{ "value": "some string" }
4BoolMetric{ "value": true }
5UsageMetric{ "value": { "used": 2048, "limit": 8192 } }
6LicenseExpirationMetric{ "value": "2025-01-01T00:00:00Z" }
7AgentSwMetric{ "value": { "updateAvailable": true } }
8AgentOperationalStateMetric{ "value": { "agentStatus": 10, "version": "5.4.0" } }
9LongMetric{ "value": 9876543210 }
10AgentRecordingMetricsee below
11ComponentInfoMetricsee below
12ConfigInfoMetricsee below

AgentRecordingMetric Example​

{
"$type": 10,
"agentRecordings": {
"agentRecorders": [
{
"recorderType": "rosbag",
"recorderState": "Recording",
"startTime": "2024-09-29T10:00:00Z",
"endTime": "2024-09-29T10:30:00Z",
"id": "rec-001",
"errorType": "",
"duration": "00:30:00"
}
]
},
"name": "AgentRecordingMetric"
}

ComponentInfoMetric Example​

{
"$type": 11,
"componentInfosDto": {
"componentsInfoDto": [
{
"componentId": "771793b9-ac7e-4b8e-8b6e-d5b84e5ba19d",
"componentUuid": "76c57d0f-e964-4082-81da-7d8f4861738b",
"version": "1.0.2",
"componentName": "Cogniteam/data-publisher-ros2-humble",
"componentState": "Active"
}
]
},
"name": "ComponentInfoMetric"
}

ConfigInfoMetric Example​

{
"$type": 12,
"configInfoDto": {
"configName": "default-config",
"version": "1.0.8",
"configState": "Ready"
},
"name": "ConfigInfoMetric"
}