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
- Cloud
- Local
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.
ws://<agent-host>:19992/apigateway/v2/robots/{robotId}/events?access_token=<token>
Connect directly to the Agent for that robot, using its ID from GET /robots. This subscription
does not forward events from local-fleet members. Use wss:// when the client trusts the Agent
certificate.
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
1008when 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 with1009.
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.501on Local: connect directly to the member Agent; WebSocket proxying through a local-fleet host is not supported.- Browser close code
1006withwss://: check that the client trusts the certificate.