Skip to main content
Version: 1.2

Alert statistics

Overview​

ToBeAlert exposes several endpoints to retrieve aggregated statistics, counts, and metadata about your alerts — without pulling the full alert list. These are ideal for dashboards, sidebars, and overview pages.

Authorization: Key YOUR_API_KEY_HERE

Get alert counts​

GET /api/alerts/count
Authorization: Key YOUR_API_KEY

Returns aggregated counts broken down by severity, status, environment, source, and trend indication, across all alerts.

Example​

Get global alert counts broken down by severity, status, environment, and more

curl -X GET "http://your-tobealert.com:9000/api/alerts/count" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

Response​

{
  "status": "ok",
  "counts": {
    "severity": {
      "critical": 5,
      "major": 3,
      "warning": 12,
      "normal": 30,
      "unknown": 2
    },
    "status": {
      "open": 17,
      "ack": 8,
      "closed": 22,
      "expired": 5
    },
    "environment": {
      "production": 25,
      "staging": 10,
      "dev": 12
    },
    "source_id": {
      "nagios": 20,
      "cloudwatch": 17,
      "null": 10
    },
    "trend_indication": {
      "moreSevere": 5,
      "lessSevere": 3,
      "noChange": 39
    },
    "total": 47
  }
}

Get alert counts for a view​

GET /api/alerts/count/by_view/<view_id>
Authorization: Key YOUR_API_KEY

Returns the same aggregated breakdown as above but scoped to the alerts matching a specific view. The user must be a member of the view or have admin scope.

Path parameters​

ParameterDescription
view_idThe ID of the view (group) to query

Example​

Get alert counts scoped to a specific view

curl -X GET "http://your-tobealert.com:9000/api/alerts/count/by_view/VIEW_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

Response​

Same structure as Get Alert Counts, but scoped to the view's alert query.

Errors​

CodeReason
403User does not have access to this view
404View not found

Get counts for multiple views​

POST /api/alerts/count_by_view
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Returns a count per view in a single request. This is the endpoint used by the UI to render badges on each view in the sidebar.

Request body​

FieldTypeRequiredDescription
viewsArrayYesList of view objects with id and name

The special id value "all_events" matches all alerts without a view filter.

Example​

Get alert counts for multiple views in a single request

curl -X POST "http://your-tobealert.com:9000/api/alerts/count_by_view" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "views": [
             {
                 "id": "all_events",
                 "name": "All Events"
             },
             {
                 "id": "view-uuid-1",
                 "name": "Production"
             },
             {
                 "id": "view-uuid-2",
                 "name": "Staging"
             }
         ]
     }'

Response​

{
  "status": "ok",
  "counts": {
    "All Events": {
      "severity": { "critical": 5, "warning": 12 },
      "status": { "open": 17, "ack": 8 },
      "total": 47
    },
    "Production": {
      "severity": { "critical": 4, "warning": 6 },
      "status": { "open": 10 },
      "total": 25
    },
    "Staging": {
      "severity": { "warning": 3 },
      "status": { "open": 3 },
      "total": 10
    }
  }
}

Errors​

CodeReason
400views field is missing or empty

Get unique types (resources, services, origins, groups, tags)​

GET /api/alerts/types
Authorization: Key YOUR_API_KEY

Returns unique values for each metadata dimension. Useful for building filter dropdowns.

Query parameters​

You can use group to request only specific dimensions. If omitted, all dimensions are returned.

ValueReturns
resourceUnique resource names
serviceUnique service names
originUnique origins
groupUnique groups
tagsAll unique tags

Example​

Get all unique resource names

curl -X GET "http://your-tobealert.com:9000/api/alerts/types?group=resource" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

Response​

{
  "status": "ok",
  "types": {
    "resources": ["web-01.example.com", "db-01.example.com", "api-gateway"],
    "services": ["web-service", "payment-service", "api-gateway"],
    "origins": ["nagios", "cloudwatch", "zabbix"],
    "groups": ["infrastructure", "backend", "cloud-infrastructure"],
    "tags": ["linux", "production", "aws", "ec2"]
  }
}

Get unique environments​

GET /api/environments
Authorization: Key YOUR_API_KEY

Returns all unique environment values present in current alerts. Supports the same filter params as alert queries.

Response​

{
  "status": "ok",
  "total": 3,
  "environments": [
    { "environment": "production", "count": 25 },
    { "environment": "staging", "count": 10 },
    { "environment": "dev", "count": 12 }
  ]
}

Get unique services​

GET /api/services
Authorization: Key YOUR_API_KEY

Returns all unique service values. Supports the same filter params as alert queries.

Response​

{
  "status": "ok",
  "total": 4,
  "services": [
    { "service": "web-service", "environment": "production" },
    { "service": "payment-service", "environment": "production" },
    { "service": "api-gateway", "environment": "staging" }
  ]
}

Get unique groups​

GET /api/alerts/groups
Authorization: Key YOUR_API_KEY

Returns all unique group values.

Response​

{
  "status": "ok",
  "total": 3,
  "groups": [
    { "group": "infrastructure", "count": 15 },
    { "group": "backend", "count": 10 },
    { "group": "cloud-infrastructure", "count": 22 }
  ]
}

Get unique tags​

GET /api/alerts/tags
Authorization: Key YOUR_API_KEY

Returns all unique tags across all alerts.

Response​

{
  "status": "ok",
  "total": 5,
  "tags": [
    { "tag": "linux", "count": 20 },
    { "tag": "production", "count": 35 },
    { "tag": "aws", "count": 18 }
  ]
}

Top N alerts by count​

GET /api/alerts/topn/count
Authorization: Key YOUR_API_KEY

Also available at /api/alerts/top10/count.

Returns the top N most frequently occurring alert events (by duplicate count). Supports the same filter params as alert queries.

Query parameters​

ParameterDefaultDescription
page-sizeConfig defaultHow many results to return (the "N" in top N)

Other filtering params (environment, severity, from-date, etc.) are also supported.

Example​

Get the top 10 most frequently occurring alerts in production

curl -X GET "http://your-tobealert.com:9000/api/alerts/topn/count?page-size=10&environment=production" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

Response​

{
  "status": "ok",
  "total": 10,
  "top10": [
    {
      "count": 150,
      "duplicateCount": 45,
      "environments": ["production"],
      "event": "HighCPUUtilization",
      "services": [["web-tier"]],
      "resource": "i-1234567890"
    },
    {
      "count": 87,
      "duplicateCount": 20,
      "environments": ["production"],
      "event": "ServerDown",
      "services": [["web-service"]],
      "resource": "web-01.example.com"
    }
  ]
}

Top N flapping alerts​

GET /api/alerts/topn/flapping
Authorization: Key YOUR_API_KEY

Also available at /api/alerts/top10/flapping.

Returns the top N alerts with trendIndication = "flapping" — alerts that have repeatedly changed severity in alternating directions.

Query parameters​

Same as Top N Alerts by Count.

Response​

Same structure as Top N by Count.

Top N standing (long-duration) alerts​

GET /api/alerts/topn/standing
Authorization: Key YOUR_API_KEY

Also available at /api/alerts/top10/standing.

Returns the top N alerts that have been open the longest without resolution.

Query parameters​

Same as Top N Alerts by Count.

Response​

Same structure as Top N by Count.