Skip to main content

Fleet Custom KPI WebSocket

A WebSocket transport for live, low-rate Custom KPI values from fleet robots. Messages are UTF-8 JSON text frames. Cloud and Local expose the same data-only FleetCustomKpiEventDto contract.

Flow​

  1. Log in with POST /auth/login.
  2. Open the fleet WebSocket.
  3. Parse each text frame as FleetCustomKpiEventDto JSON.
  4. Read updates[].

Endpoint​

wss://api.cognimbus.com/apigateway/v2/fleets/{fleetId}/custom-kpis?access_token=<token>

Replace {fleetId} with the fleet id from your organization. For the Asia region, use api.ap1.cognimbus.com.

The request must be a WebSocket upgrade. Browser clients put the token in the query string because the WebSocket constructor cannot set an Authorization header. Remove the leading bearer prefix from the login response before constructing the URL.

Payload​

Each Cloud or Local frame has the same data-only shape:

{
  "updates": [
    {
      "basicData": { "id": "robot-1", "name": "AMR-01" },
      "updateTime": "2026-08-02T10:15:30Z",
      "metric": {
        "name": "robot_pose",
        "dataType": "Nimbus.Messages.geometry_msgs.Pose",
        "value": {
          "position": { "x": 1.25, "y": -2.5, "z": 0.0 },
          "orientation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 }
        }
      }
    }
  ]
}

metric.value is a native JSON scalar or object. The gateway decodes structured KPI protobuf values, so Fleet KPI clients do not need Nimbus protobuf descriptors. KPI state, status, settings, regular telemetry, connectivity events, resources, and raw MessageStream envelopes are not part of this frame.

C# Client​

Add Cogniteam.ApiGateway.Client from the Cogniteam NuGet source configured for your organization. The same client works with Cloud and Local base URLs:

using Cogniteam.ApiGateway.Client;

async Task ReadFleetCustomKpisAsync(
    string baseUrl,
    string bearerToken,
    string fleetId,
    CancellationToken cancellationToken)
{
    var client = new NimbusApiGatewayClient(new Uri(baseUrl), bearerToken);

    await foreach (var frame in client.StreamFleetCustomKpisAsync(fleetId, cancellationToken))
    {
        foreach (var update in frame.Updates)
        {
            Console.WriteLine(
                $"{update.BasicData.Id} {update.Metric.DataType} {update.Metric.Value.GetRawText()}");
        }
    }
}

bearerToken is the token returned by the environment's login endpoint. The Client removes an optional leading bearer prefix, sends the token as access_token, opens the canonical route, and deserializes every JSON text frame as FleetCustomKpiEventDto. HTTPS/WSS connections require a trusted certificate.

Browser Example​

function connectFleetCustomKpis(baseUrl, fleetId, bearerToken) {
  const token = bearerToken.replace(/^bearer\s+/i, '');
  const url = new URL(baseUrl);
  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
  const socket = new WebSocket(
    `${url.origin}/apigateway/v2/fleets/${encodeURIComponent(fleetId)}/custom-kpis?access_token=${encodeURIComponent(token)}`
  );

  socket.onmessage = event => {
    const frame = JSON.parse(event.data);
    for (const update of frame.updates) {
      console.log(update.basicData.id, update.metric.dataType, update.metric.value);
    }
  };
  return socket;
}

Delivery Semantics​

  • Delivery is live and best-effort; this is not a replay API.
  • Slow clients can drop frames, and reconnect does not recover missed values.
  • Custom KPI collection normally runs once per second.
  • The gateway does not resample, interpolate, or increase pose frequency.

For higher-rate data, use Data Streams in Cloud or the Local Live Stream WebSocket.

Common Errors​

  • 400: the request is not a WebSocket upgrade.
  • 401: the token is missing, expired, or invalid.
  • 404: the fleet id is not available. Local clients must use local-fleet.
  • Local browser close code 1006: the browser may not trust the wss:// certificate.