Skip to main content

Robot Live Events WebSocket

Subscribe to new events from one robot. Cloud and Local send the same basic RobotLiveEventDto as one UTF-8 JSON text message per occurrence.

Endpoint​

wss://api.cognimbus.com/apigateway/v2/robots/{robotId}/events?access_token=<token>

For the Asia region, use api.ap1.cognimbus.com. The robot must be accessible to the caller.

Log in first using the environment's authentication endpoint. Browser clients use access_token because the WebSocket constructor cannot set an Authorization header. Remove an optional leading bearer prefix from the token before constructing the URL.

Payload​

{
"id": "event-1",
"timestamp": "2026-11-18T10:15:30Z",
"basicData": { "id": "robot-1", "name": "AMR-01" },
"manager": "Task",
"level": "Info",
"message": "Inspection started"
}

id identifies the occurrence. timestamp is its original occurrence time in UTC, not the time the viewer received it. manager and level are strings. The frame contains the basic summary; captured payloads, attachments and task execution details belong to separate history views.

Delivery​

  • Subscriptions receive new occurrences only. Connecting or reconnecting does not replay events.
  • An open Local subscription works without a cloud connection. A later cloud reconnect does not replay the Agent's pending history into this local live feed.
  • Later attachment or upload-status changes update saved history, rather than emitting another occurrence here.
  • There is no per-event acknowledgment. A disconnect can leave a gap; refresh history separately when a complete record is needed. See the local event history commands.
  • Local delivery keeps a bounded queue of 128 events per subscriber. If a viewer falls behind, the Agent disconnects it with WebSocket close code 1008 when a closing handshake is possible, rather than silently replacing events. Cancelling an in-flight socket send can instead result in an abnormal disconnect; the overflow counter still records the gap. An event exceeding the public message-size limit closes the connection with 1009.

The Local Agent does not discard a new occurrence merely because its timestamp is old.

C# Client​

Use Cogniteam.ApiGateway.Client from your organization's configured Cogniteam NuGet source:

using Cogniteam.ApiGateway.Client;

var client = new NimbusApiGatewayClient(new Uri(baseUrl), bearerToken);
await foreach (var occurrence in client.StreamRobotEventsAsync(robotId, cancellationToken))
{
Console.WriteLine($"{occurrence.Timestamp:O} {occurrence.Level}: {occurrence.Message}");
}

The same helper works with Cloud and Local base URLs. It handles the token prefix, WebSocket URL, JSON decoding and cancellation. Reconnect explicitly to start a new subscription.

Browser Example​

const url = new URL(baseUrl);
url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
url.pathname = `/apigateway/v2/robots/${encodeURIComponent(robotId)}/events`;
url.search = new URLSearchParams({
access_token: bearerToken.replace(/^bearer\s+/i, ''),
}).toString();

const socket = new WebSocket(url);
socket.onmessage = event => console.log(JSON.parse(event.data));
socket.onclose = event => console.log('Live events disconnected', event.code, event.reason);

Local Debug Viewer​

Open /debug/local-api-gateway/robot-events on the Agent. The viewer consumes this public WebSocket route and shows disconnects; it does not read history directly. Embedded same-Agent tools can select their authenticated operator session with operator_session=true instead of putting a bearer token into page JavaScript.

GET /api/local-api-gateway/robot-events/diagnostics reports in-process published-event, active-subscription and overflow counts. These counters reset when the Agent restarts.

Common Errors​

  • 400: the request is not a WebSocket upgrade.
  • 401: authentication is missing or invalid.
  • 403: Local API Gateway is disabled.
  • 404: the requested robot is not available on this host or to this caller.
  • 501 on Local: connect directly to the member Agent; WebSocket proxying through a local-fleet host is not supported.
  • Browser close code 1006 with wss://: check that the client trusts the certificate.