# Stats Endpoints (/operate/observability/api-reference/stats)



The statistics endpoints under `/v1/stats/` return raw metrics for queues, events stores,
channels, and clients. All responses use the standard response envelope (see the
[Management API overview](/operate/observability/api-reference)) and are **gzip-compressed**.

For dashboards, prefer the pre-aggregated
[snapshot endpoints](/operate/observability/api-reference/dashboard-endpoints) — they return
ready-to-render DTOs rather than raw, compressed statistics.

## GET /v1/stats/queues [#get-v1statsqueues]

Returns queue storage statistics from the persistence engine.

**Response data — `Queues`:**

```json
{
  "now": "2024-03-01T12:00:00Z",
  "total_queues": 5,
  "sent": 10000,
  "waiting": 250,
  "delivered": 9750,
  "queues": [
    {
      "name": "orders.process",
      "messages": 500,
      "bytes": 102400,
      "first_sequence": 1,
      "last_sequence": 500,
      "sent": 500,
      "subscribers": 2,
      "waiting": 50,
      "delivered": 450
    }
  ]
}
```

| Field          | Type               | Description                                |
| -------------- | ------------------ | ------------------------------------------ |
| `now`          | `string` (RFC3339) | Server timestamp                           |
| `total_queues` | `int`              | Total number of queue channels             |
| `sent`         | `int64`            | Total messages sent across all queues      |
| `waiting`      | `int64`            | Total messages waiting across all queues   |
| `delivered`    | `int64`            | Total messages delivered across all queues |
| `queues`       | `Queue[]`          | Per-queue detail array                     |

Each entry in `queues` is a `Queue`:

| Field            | Type     | Description                        |
| ---------------- | -------- | ---------------------------------- |
| `name`           | `string` | Queue channel name                 |
| `messages`       | `int64`  | Total stored messages              |
| `bytes`          | `int64`  | Total stored bytes                 |
| `first_sequence` | `int64`  | First message sequence number      |
| `last_sequence`  | `int64`  | Last message sequence number       |
| `sent`           | `int64`  | Messages sent to this queue        |
| `subscribers`    | `int`    | Active subscriber count            |
| `waiting`        | `int64`  | Messages waiting for delivery      |
| `delivered`      | `int64`  | Messages delivered from this queue |

## GET /v1/stats/events\_stores [#get-v1statsevents_stores]

Returns events store statistics from the persistence engine. Events stores are backed by
the same persistence layer as queues, so this endpoint returns the same `Queues` schema as
[`GET /v1/stats/queues`](#get-v1statsqueues).

## GET /v1/stats/channels [#get-v1statschannels]

Returns all channel statistics with a per-type summary.

**Response data — `ChannelsResponse`:**

```json
{
  "Host": "kubemq-node-0",
  "LastUpdate": "2024-03-01T12:00:00Z",
  "Channels": [
    {
      "kind": "queues",
      "name": "orders.process",
      "total_messages": 5000,
      "total_volume": 1024000,
      "total_errors": 0
    },
    {
      "kind": "events",
      "name": "notifications",
      "total_messages": 12000,
      "total_volume": 240000,
      "total_errors": 5
    }
  ],
  "Summery": [
    {
      "kind": "queues",
      "total_channels": 3,
      "total_messages": 15000,
      "total_volume": 3072000,
      "total_errors": 2
    }
  ]
}
```

| Field        | Type                | Description                          |
| ------------ | ------------------- | ------------------------------------ |
| `Host`       | `string`            | Node hostname                        |
| `LastUpdate` | `string` (RFC3339)  | Timestamp of the last metrics update |
| `Channels`   | `ChannelStats[]`    | Per-channel statistics               |
| `Summery`    | `ChannelsSummery[]` | Per-type aggregated summary          |

Each entry in `Channels` is a `ChannelStats`:

| Field            | Type      | Description                                                                |
| ---------------- | --------- | -------------------------------------------------------------------------- |
| `kind`           | `string`  | Channel type: `queues`, `events`, `events_store`, `commands`, or `queries` |
| `name`           | `string`  | Channel name                                                               |
| `total_messages` | `float64` | Total messages through this channel                                        |
| `total_volume`   | `float64` | Total data volume in bytes                                                 |
| `total_errors`   | `float64` | Total errors on this channel                                               |

Each entry in `Summery` is a `ChannelsSummery`:

| Field            | Type      | Description                     |
| ---------------- | --------- | ------------------------------- |
| `kind`           | `string`  | Channel type                    |
| `total_channels` | `int`     | Number of channels of this type |
| `total_messages` | `float64` | Aggregate messages              |
| `total_volume`   | `float64` | Aggregate volume                |
| `total_errors`   | `float64` | Aggregate errors                |

## GET /v1/stats/clients [#get-v1statsclients]

Returns all connected client statistics with aggregated totals.

**Response data — `ClientResponse`:**

```json
{
  "Host": "kubemq-node-0",
  "LastUpdate": "2024-03-01T12:00:00Z",
  "TotalClients": 12,
  "TotalMessages": 50000,
  "TotalVolume": 10240000,
  "TotalErrors": 5,
  "TotalOnline": 8,
  "Clients": [
    {
      "name": "order-service-1",
      "total_messages": 5000,
      "total_volume": 1024000,
      "total_errors": 0,
      "total_pending": 10
    }
  ]
}
```

| Field           | Type               | Description                          |
| --------------- | ------------------ | ------------------------------------ |
| `Host`          | `string`           | Node hostname                        |
| `LastUpdate`    | `string` (RFC3339) | Timestamp of the last metrics update |
| `TotalClients`  | `int`              | Total unique clients                 |
| `TotalMessages` | `float64`          | Sum of all client messages           |
| `TotalVolume`   | `float64`          | Sum of all client volume             |
| `TotalErrors`   | `float64`          | Sum of all client errors             |
| `TotalOnline`   | `int`              | Currently connected clients          |
| `Clients`       | `ClientsStats[]`   | Per-client statistics                |

Each entry in `Clients` is a `ClientsStats`:

| Field            | Type      | Description                    |
| ---------------- | --------- | ------------------------------ |
| `name`           | `string`  | Client identifier              |
| `total_messages` | `float64` | Total messages for this client |
| `total_volume`   | `float64` | Total volume in bytes          |
| `total_errors`   | `float64` | Total errors                   |
| `total_pending`  | `float64` | Pending messages               |

## GET /v1/stats/attach [#get-v1statsattach]

A WebSocket endpoint for real-time monitoring. It is an alias for `/api/monitor`, mounted
under the stats group, and takes the same query parameters. See
[WebSocket Protocols](/operate/observability/api-reference/websockets) for the monitor
protocol and transport frames.