# Dashboard Endpoints (/operate/observability/api-reference/dashboard-endpoints)



These endpoints power the built-in dashboard. They return pre-aggregated, UI-ready data
structures with humanized values — formatted numbers, relative timestamps, and percentages
alongside the raw values. They all live under `/api/` on the management API port (`:8080`),
use the [standard response envelope](/operate/observability/api-reference), and are gated by
the readiness check.

The snapshot payloads contain many nested DTOs. This page documents the **top-level shape**
of each response; for the full field-by-field schema of every nested type, see
[Data Models](/operate/observability/api-reference/data-models).

<Callout title="Poll, don't hammer">
  The server recomputes the snapshot internally every **5 seconds**. Polling faster than that
  returns the same data — poll the snapshot endpoints every **5–10 seconds**. For a
  push-based stream instead of polling, use the
  [`/api/connection` WebSocket](/operate/observability/api-reference/websockets).
</Callout>

## GET /api/snapshot [#get-apisnapshot]

Returns the current single-node snapshot — everything needed to render the dashboard for one
KubeMQ node: host info, topology, stat cards, per-channel detail, and per-client detail. The
response `data` is a `SnapshotDTO`.

```json
{
  "error": false,
  "error_string": "",
  "data": {
    "hostsInfo": [
      {
        "host": "kubemq-node-0",
        "version": "2.5.0",
        "status": "Running",
        "role": "Leader",
        "uptime": "24h0m0s",
        "activeClients": 8
      }
    ],
    "topologyNodes": {
      "clusterNodesList": ["kubemq-node-0", "kubemq-node-1"],
      "clientNodesList": ["order-service", "payment-service"],
      "clusterClientConnections": [
        { "clusterNode": 0, "clientNode": 0 },
        { "clusterNode": 0, "clientNode": 1 }
      ]
    },
    "trafficChannels": {
      "channels": {
        "queues/orders": [
          { "clientId": "order-service", "side": "send" },
          { "clientId": "payment-service", "side": "receive" }
        ]
      }
    },
    "statsCards": { "...": "StatCardDTOs" },
    "topChannels": [
      {
        "type": "Queue",
        "channel": "orders.process",
        "lastActivity": "2 seconds ago",
        "sent": "5,000/4.9 MB",
        "delivered": "4,800/4.7 MB",
        "clients": "3/5"
      }
    ],
    "lastActivity": 1709312400000,
    "lastActivityHuman": "2 seconds ago",
    "total": { "...": "BaseValuesDTO" },
    "incoming": { "...": "BaseValuesDTO" },
    "outgoing": { "...": "BaseValuesDTO" },
    "channels": 10,
    "clients": 8,
    "activeChannels": 5,
    "queues": { "...": "FamilyDTO" },
    "pubsub": { "...": "FamilyDTO" },
    "commandsQueries": { "...": "FamilyDTO" },
    "nodeType": "standalone",
    "node": "kubemq-node-0"
  }
}
```

### Top-level fields [#top-level-fields]

| Field               | Type                 | Description                                                                     |
| ------------------- | -------------------- | ------------------------------------------------------------------------------- |
| `hostsInfo`         | `HostInfoDTO[]`      | System info for each node — memory, CPU, storage, uptime, role, active clients. |
| `topologyNodes`     | `TopologyNodesDTO`   | Cluster-to-client connection graph for the topology visualization.              |
| `trafficChannels`   | `TrafficChannelsDTO` | Per-channel client connections with the send/receive side.                      |
| `statsCards`        | `StatCardDTOs`       | Pre-computed overview cards (channels, clients, incoming, outgoing).            |
| `topChannels`       | `TopChannelDTO[]`    | The 10 most recently active channels.                                           |
| `lastActivity`      | `int64`              | Unix timestamp (ms) of the last activity across all channels.                   |
| `lastActivityHuman` | `string`             | Human-readable relative time (e.g. `"2 seconds ago"`).                          |
| `total`             | `BaseValuesDTO`      | Combined incoming + outgoing totals.                                            |
| `incoming`          | `BaseValuesDTO`      | Aggregate incoming metrics.                                                     |
| `outgoing`          | `BaseValuesDTO`      | Aggregate outgoing metrics.                                                     |
| `channels`          | `int64`              | Total channel count.                                                            |
| `clients`           | `int64`              | Total client count.                                                             |
| `activeChannels`    | `int64`              | Number of currently active channels.                                            |
| `queues`            | `FamilyDTO`          | The Queues family — full per-channel and per-client detail.                     |
| `pubsub`            | `FamilyDTO`          | The Pub/Sub family (Events + Events Store combined).                            |
| `commandsQueries`   | `FamilyDTO`          | The CQRS family (Commands + Queries combined).                                  |
| `nodeType`          | `string`             | Node type from configuration.                                                   |
| `node`              | `string`             | Node hostname.                                                                  |

Use `statsCards` for the overview cards, `topChannels` for the recent-activity table,
`hostsInfo` for node health, `topologyNodes` for the cluster graph, and the three
`FamilyDTO` objects (`queues`, `pubsub`, `commandsQueries`) for the detailed channel and
client views. Each humanized value has a raw counterpart (e.g. `lastActivity` /
`lastActivityHuman`); see [Data Models](/operate/observability/api-reference/data-models) for
the complete nested schemas.

## GET /api/cluster-snapshot [#get-apicluster-snapshot]

Returns the cluster-wide aggregated snapshot. In a multi-node cluster this merges data from
every node; in standalone mode it is equivalent to `/api/snapshot`.

The response uses the **same `SnapshotDTO` schema** as `/api/snapshot`, with data aggregated
across all cluster nodes:

* `hostsInfo` contains one entry per node.
* Channel and client entities are combined across nodes.
* Queue waiting counts reflect the cluster total.

Use this endpoint for the cluster-wide dashboard view.

## GET /api/last-diff [#get-apilast-diff]

Returns time-bucketed channel activity — historical time-series data showing how each
channel's metrics changed over a set of time windows. This is the data behind the
dashboard's sparklines and activity charts.

The response `data` is a **channel-first** nested map:

```text
map[channel]            → channel key, format "{type}/{name}"
  map[resolution]       → resolution key, e.g. "1h", "7d"
    TimeBucket
      resolution        → resolution identifier
      items[]           → data points (up to 30 per resolution)
```

```json
{
  "error": false,
  "error_string": "",
  "data": {
    "queues/orders": {
      "1h": {
        "resolution": "1h",
        "items": [
          {
            "timestamp": "2024-03-01T11:00:00Z",
            "inMessages": 100,
            "inVolume": 20480,
            "outMessages": 95,
            "outVolume": 19456
          },
          {
            "timestamp": "2024-03-01T11:02:00Z",
            "inMessages": 50,
            "inVolume": 10240,
            "outMessages": 48,
            "outVolume": 9830
          }
        ]
      },
      "1d": {
        "resolution": "1d",
        "items": [
          {
            "timestamp": "2024-03-01T00:00:00Z",
            "inMessages": 5000,
            "inVolume": 1024000,
            "outMessages": 4800,
            "outVolume": 983040
          }
        ]
      }
    }
  }
}
```

### TimeBucket [#timebucket]

| Field        | Type               | Description                                              |
| ------------ | ------------------ | -------------------------------------------------------- |
| `resolution` | `string`           | Resolution identifier (see the table below).             |
| `items`      | `TimeBucketItem[]` | Up to 30 data points, zero-padded if fewer points exist. |

### TimeBucketItem [#timebucketitem]

| Field         | Type               | Description                                  |
| ------------- | ------------------ | -------------------------------------------- |
| `timestamp`   | `string` (RFC3339) | Start of the time bucket.                    |
| `inMessages`  | `int64`            | Incoming message-count delta for the bucket. |
| `inVolume`    | `int64`            | Incoming volume delta (bytes).               |
| `outMessages` | `int64`            | Outgoing message-count delta.                |
| `outVolume`   | `int64`            | Outgoing volume delta (bytes).               |

### Resolutions [#resolutions]

Every channel carries data at all eight resolutions; each resolution holds up to 30 data
points covering its window.

| Resolution | Time range    | Point interval |
| ---------- | ------------- | -------------- |
| `1h`       | Last 1 hour   | 2 minutes      |
| `2h`       | Last 2 hours  | 4 minutes      |
| `6h`       | Last 6 hours  | 12 minutes     |
| `12h`      | Last 12 hours | 24 minutes     |
| `1d`       | Last 24 hours | 48 minutes     |
| `7d`       | Last 7 days   | 5.6 hours      |
| `14d`      | Last 14 days  | 11.2 hours     |
| `30d`      | Last 30 days  | 24 hours       |

To render a sparkline for a channel, look up its key (e.g. `"queues/orders"`), pick a
resolution, and plot the `items` array.

## GET /api/agents [#get-apiagents]

Returns the registered AI agents as a paginated list. This is one of the AI-dashboard
endpoints behind the dashboard's agents area; see the
[Prometheus metrics page](/operate/observability/metrics) for the agent-platform metric series.

### Query parameters [#query-parameters]

| Parameter | Type  | Default | Description                                                              |
| --------- | ----- | ------- | ------------------------------------------------------------------------ |
| `offset`  | `int` | `0`     | Zero-based index of the first agent to return.                           |
| `limit`   | `int` | `50`    | Maximum agents to return. Capped at **100** — larger values are clamped. |

```bash
curl "http://localhost:8080/api/agents?offset=0&limit=50"
```

The response uses the [standard envelope](/operate/observability/api-reference); `data` is the
paginated list of registered agents with their presence and lifetime stats.

## GET /api/agents/:id [#get-apiagentsid]

Returns the detail for a single registered agent, identified by the `:id` path parameter.
The response `data` carries the agent's record plus a stats snapshot — lifetime request,
error, and latency totals along with per-method and per-outcome breakdowns.

```bash
curl "http://localhost:8080/api/agents/order-router"
```

Like the list endpoint, the agent detail uses the
[standard envelope](/operate/observability/api-reference).

## Related [#related]

<Cards>
  <Card title="Data Models" href="/operate/observability/api-reference/data-models" description="Full field-by-field schemas for SnapshotDTO and every nested dashboard DTO." />

  <Card title="WebSocket Protocols" href="/operate/observability/api-reference/websockets" description="The 2-second cluster snapshot stream as a push alternative to polling." />
</Cards>