Alerts

This article refers to SDK version v0.5.0. The current SDK version is N/A.

Overview

client.alerts covers the alerts raised across your fleet and the events behind them. These are the same alerts triggered by the Alert Manager Marketplace app once it's deployed and configured on a node, whether from disk-usage thresholds, service health checks, or external variables posted to its REST endpoint.

This guide is the read and acknowledge side of that pipeline. It doesn't configure the Alert Manager itself, see the Alert Manager article for the App Config fields (disk_alarm_warning_threshold, services, and so on) that decide when an alert fires in the first place.

Concept

Alert Manager. A Marketplace app an operator deploys to a node to watch disk usage, service health, or custom variables, and raise alerts in Barbara Panel when something crosses a threshold.

Learn more→

List alerts

alerts = client.alerts.list()
alert = client.alerts.get("<alert-id>")

list(*, offset=0, size=100) returns a List[Alert]. offset and size page through results the same way client.nodes.paginate does elsewhere in the SDK: offset is the number of alerts to skip, size (default 100) the maximum to return. Each Alert has:

Field	Type	What it is
id	str	The alert's internal identifier, what get, ack, and list_events's filtering all expect
title	Optional[str]	The alert's human-readable title, for example the name you set when posting an external variable event like "Low pressure"
severity	Optional[int]	A numeric severity code; higher generally means more urgent, but the exact scale isn't published in the SDK docstrings, cross-check against a known alert's raw payload if you need to branch on it
active	Optional[bool]	Whether the alert is still ongoing (True) or has cleared (False)
node_id	Optional[str]	The node that raised the alert, matching the deviceDisplayName context from the Alert Manager's own event payloads
raw	Dict[str, Any]	The full untyped API response for this alert

get(alert_id) fetches a single Alert by the id from the list above.

Default page size is always sent

The API itself defaults size to 0 (no results) when it's omitted, but list() always sends an explicit default of 100 for you, so you get results back without having to think about it.

Acknowledge one

client.alerts.ack("<alert-id>")

ack(alert_id) marks the alert as acknowledged and returns the updated Alert directly, unlike most write methods in the SDK, so you don't need a follow-up get() to confirm the acknowledgement landed.

Remember that...

Acknowledging an alert does not clear it. active stays True until the underlying condition (disk usage back under threshold, service healthy again) resolves itself on its own. Acknowledging is purely a record that a human has seen it, useful when building a triage script that pages on new, unacknowledged alerts only.

Inspect the events behind an alert

events = client.alerts.list_events(node_id="<node-id>")
event = client.alerts.get_event("<event-id>")

list_events(*, offset=0, size=100, node_id=None) returns List[AlertEvent], the individual occurrences that make up an alert's history, comparable to what the Alert Manager's daily summary email digests. Filter by node_id to see only the events from one node, or omit it for the whole company. Each AlertEvent has:

Field	Type	What it is
id	str	The event's internal identifier, what get_event expects
event_type	Optional[int]	A numeric code for the kind of event (raised, cleared, ...); not enumerated in the SDK docstrings
node_id	Optional[str]	The node this specific event came from
alert_id	Optional[str]	The id of the parent Alert this event belongs to, letting you correlate list_events() output back to client.alerts.get(alert_id)
raw	Dict[str, Any]	The full untyped API response for this event

get_event(event_id) fetches a single one directly.

Filter events by alert

Since list_events doesn't filter by alert_id directly, the pattern for reading every event behind one specific alert is to call list_events(node_id=alert.node_id) and then filter the returned list in Python by event.alert_id == alert.id.

Summary

You can now pull the current alert picture for your fleet, acknowledge what you've triaged, and drill into the events behind a specific alert.

This pairs well with a scheduled script: list alerts on an interval, and page or log the ones that are still active and unacknowledged.

For the full method list, see client.alerts in the Reference.