# Aggregate alert statistics

**GET /alerts/stats**

Returns aggregate statistics over `alert_history` for the caller's scope:
total, severity buckets, top-N alertname and system_key by count, plus MTTR
(mean time to resolve) and MTBF (mean time between failures, approximated).

Scope follows the same three modes as `/alerts/totals`:
- `organization_id` omitted → caller's full hierarchy.
- `organization_id=X` → single tenant.
- `organization_id=X&include=descendants` → sub-tree drill-down.

MTBF formula:
- When both `from_date` and `to_date` are provided: `(to - from) / total`.
- Otherwise: `(max(starts_at) - min(starts_at)) / (total - 1)`.
- Omitted from the response when the result is undefined.



## Servers
- Backend API server (port 8080): https://api.your-domain.com/api (Backend API server (port 8080))
- Collect API server (port 8081): https://collect.your-domain.com/api (Collect API server (port 8081))


## Authentication methods
- Bearer auth


## Parameters


### Query parameters
- **organization_id** (string)

- **include** (string)

- **from_date** (string(date-time))
  Lower bound on `created_at` (inclusive). RFC3339 timestamp.
- **to_date** (string(date-time))
  Upper bound on `created_at` (exclusive). RFC3339 timestamp.
- **top** (integer)
  Cap for top-N alertname / system_key buckets. Default 10, max 50.


## Responses
### 200
Alert stats retrieved

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object)


### 400
Bad request - validation error

#### Body: application/json (object)
- **code** (integer)
  HTTP error code
- **message** (string)
  Error message
- **data** (object)


### 401
Unauthorized - invalid or missing token

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object | null)


### 403
Forbidden - insufficient permissions

#### Body: application/json (object)
- **code** (integer)

- **message** (string)

- **data** (object | null)



[Powered by Bump.sh](https://bump.sh)