/alerts/totals - Get alert totals by severity

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api.my.nethesis.it/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}
Close
GET /alerts/totals
Bearer auth

Returns active alert counts by severity and total resolved alert history count. Requires read:systems permission.

Scope modes (selected by query params):

organization_id include Result
omitted — Caller's full hierarchy (recursive). For Customer it's just self.
X omitted Single tenant X only. Resellers/Distributors hold no alerts on their own tenant — those live on their customer tenants — so single-tenant queries on a non-leaf org typically return zero.
X (repeated for multi) omitted Union of all organization_id values passed. Each must be in the caller's hierarchy (Owner exempt).
X (single or multi) descendants Each org_id is expanded to itself + its sub-tree (deduplicated). Use this to drill into one or more sub-trees.

Active counts come from alerts_totals_by_org, a per-organization pre-aggregated table maintained by the collect service's AlertsTotalsRefresher cron (one Mimir round-trip per tenant every 60s, off the user request path). The endpoint resolves the response with a single SQL SUM scoped to the caller's hierarchy, so latency is independent of how many tenants are in scope. The history total comes from a single SQL query against alert_history scoped to the same set of organization IDs.

When the freshest row in scope is older than 5 minutes (refresher lagging or down), the response carries a warnings[] entry (totals: stale data, oldest refresh Xs ago); counts are still served as last known. DB errors on either table are likewise non-fatal and surface as warnings[] entries.

Customer callers are always pinned to their own organization regardless of organization_id/include.

Query parameters

  • organization_id array[string]

    Target organization ID(s). Repeat the param to pass multiple values (?organization_id=A&organization_id=B). Optional for all roles except Customer (where it is ignored). Distributors/Resellers receive 403 if any value is not in their hierarchy.

  • include string

    Set to descendants together with organization_id to expand each value to its full sub-tree (results deduplicated). Ignored when organization_id is omitted (the caller's own hierarchy is already used) and when the caller is a Customer.

    Value is descendants.

Responses

  • 200 application/json

    Alert totals retrieved

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • active integer

        Total active alerts in scope

      • critical integer

        Active critical alerts in scope

      • warning integer

        Active warning alerts in scope

      • info integer

        Active info alerts in scope

      • muted integer

        Active alerts currently silenced (Alertmanager silencedBy non-empty)

      • history integer

        Total resolved alerts in history (DB) in scope

      • warnings array[string]

        Non-fatal degradation messages. Always present (empty array when the response is fully fresh). Possible entries: totals: stale data, oldest refresh Xs ago (refresher is lagging or down), totals: <error> (DB error reading alerts_totals_by_org), history: <error> (DB error reading alert_history).
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 403 application/json

    Forbidden - insufficient permissions

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
GET /alerts/totals 
curl \
 --request GET 'https://collect.your-domain.com/api/alerts/totals' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "code": 200,
  "message": "alert totals retrieved successfully",
  "data": {
    "active": 42,
    "critical": 42,
    "warning": 42,
    "info": 42,
    "muted": 42,
    "history": 42,
    "warnings": [
      "string"
    ]
  }
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}
Response examples (403) 
{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}