Documentation
Documentation
https://learn.netdata.cloud/docs/rest-api/api
Authentication
https://learn.netdata.cloud/docs/netdata-cloud/authentication-&-authorization/api-tokens
OpenAPI Specification
openapi: 3.0.0
info:
title: Netdata agent alerts API
description: 'Real-time performance and health monitoring.
## API Versions
Netdata provides three API versions:
- **v1**: The original API, focused on single-node operations
- **v2**: Multi-node API with advanced grouping and aggregation capabilities
- **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features
### v3 API Endpoints
The v3 API provides the current, actively maintained endpoints:
- `/api/v3/data` - Multi-dimensional data queries
- `/api/v3/weights` - Metric scoring/correlation
- `/api/v3/contexts` - Context metadata
- `/api/v3/nodes` - Node information
- `/api/v3/q` - Full-text search
- `/api/v3/alerts` - Alert information
- `/api/v3/alert_transitions` - Alert state transitions
- `/api/v3/alert_config` - Alert configuration
- `/api/v3/functions` - Available functions
- `/api/v3/function` - Execute functions
- `/api/v3/info` - Agent information
- `/api/v3/node_instances` - Node instance information
- `/api/v3/stream_path` - Streaming topology
- `/api/v3/versions` - Version information
- `/api/v3/badge.svg` - Dynamic badges
- `/api/v3/allmetrics` - Export metrics
- `/api/v3/context` - Single context info
- `/api/v3/variable` - Variable information
- `/api/v3/config` - Dynamic configuration
- `/api/v3/settings` - Agent settings
- `/api/v3/me` - Current user information
- `/api/v3/claim` - Agent claiming
- Additional management and streaming endpoints
**Note:** V1 and V2 APIs are deprecated and maintained for backwards compatibility only. New integrations should use V3 exclusively.
'
version: v1-rolling
contact:
name: Netdata Agent API
email: info@netdata.cloud
url: https://netdata.cloud
license:
name: GPL v3+
url: https://github.com/netdata/netdata/blob/master/LICENSE
servers:
- url: https://registry.my-netdata.io
- url: http://registry.my-netdata.io
- url: http://localhost:19999
tags:
- name: alerts
description: Everything related to alerts
paths:
/api/v3/alerts:
get:
operationId: alerts3
tags:
- alerts
summary: Current Alert Status - Multi-node Alert Information - Latest API
description: 'Returns the current status of all alerts across all nodes monitored by this Netdata agent.
This is the latest version (v3) of the alerts API. It provides the same functionality as v2 but may include additional features in the future.
**What This API Provides:**
- Current state of all active, warning, and critical alerts
- Alert values and thresholds
- Alert configuration summaries
- Multi-node alert aggregation
- Filtering by alert name, context, node, or status
**Use Cases:**
- Dashboard alert widgets showing current system health
- Alert management interfaces
- Integration with external alerting systems
- Monitoring alert coverage across infrastructure
- Finding all alerts in specific states (warning/critical)
**Response Content:**
The response includes comprehensive information about alerts including their current values, configured thresholds, time in current state, and associated context/chart information.
**Security & Access Control:**
- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply
- **Default Access:** Public (no authentication required)
- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token
- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf
- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools
'
security:
- {}
- bearerAuth: []
parameters:
- $ref: '#/components/parameters/scopeNodes'
- $ref: '#/components/parameters/scopeContexts'
- $ref: '#/components/parameters/filterNodes'
- $ref: '#/components/parameters/filterContexts'
- name: alert
in: query
description: 'Filter alerts by alert name pattern. Uses Netdata simple pattern matching.
**Pattern Syntax:**
- Exact match: `cpu_usage`
- Wildcard: `cpu_*` (all CPU-related alerts)
- Multiple patterns: `cpu_* ram_*` (space-separated)
- Negation: `!cpu_usage` (all except this alert)
**Common Alert Names:**
- `ram_in_use` - RAM utilization
- `disk_space_usage` - Disk space
- `10min_cpu_usage` - CPU usage over 10 minutes
- `tcp_listen_overflows` - TCP connection queue overflows
- `disk_backlog` - Disk I/O backlog
When not specified, all alerts are included.
**Examples:**
- `alert=ram_in_use` - Only RAM usage alert
- `alert=*cpu*` - All CPU-related alerts
- `alert=* !*_critical` - All alerts except those ending with _critical
'
required: false
schema:
type: string
examples:
single:
value: ram_in_use
summary: Single alert
pattern:
value: '*cpu*'
summary: All CPU alerts
- name: status
in: query
description: 'Filter alerts by their current status. Can specify multiple statuses.
**Alert Statuses:**
- `CRITICAL` - Alert is in critical state (highest severity)
- `WARNING` - Alert is in warning state
- `CLEAR` - Alert is in normal state (not triggered)
- `UNDEFINED` - Alert could not be evaluated (e.g., division by zero, missing data)
- `UNINITIALIZED` - Alert has not been evaluated yet (no data collected)
**Multiple Statuses:**
To show multiple statuses, separate them with commas: `status=CRITICAL,WARNING`
**Use Cases:**
- `status=CRITICAL` - Show only critical alerts requiring immediate attention
- `status=CRITICAL,WARNING` - Show all alerts that need attention
- `status=CLEAR` - Show alerts that are currently in normal state
- Not specified - Show alerts in all states
**Default:** When not specified, typically returns only alerts in WARNING or CRITICAL state (this depends on options parameter).
'
required: false
schema:
type: string
examples:
critical_only:
value: CRITICAL
summary: Only critical alerts
needs_attention:
value: CRITICAL,WARNING
summary: All alerts needing attention
all_states:
value: CRITICAL,WARNING,CLEAR,UNDEFINED,UNINITIALIZED
summary: All alert states
- name: options
in: query
description: 'Comma or pipe-separated list of options to control response content.
**Alert-Specific Options:**
- `summary` - Include summary counters (total alerts, by status, by type)
**General Options:**
- `contexts` - Include context information
- `instances` - Include alert instance details
- `values` - Include current alert values
- `configurations` - Include alert configuration details
**Examples:**
- `options=summary` - Include alert count summaries
- `options=summary,values` - Summaries and current values
- `options=summary|configurations` - Summaries and configs (pipe separator)
When not specified, returns basic alert information without detailed configs or summaries.
'
required: false
schema:
type: string
examples:
basic:
value: summary
summary: With summary counters
detailed:
value: summary,values,configurations
summary: Complete alert information
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- name: timeout
in: query
description: 'Maximum time in milliseconds to wait for the query to complete.
This is useful for preventing long-running queries from blocking when querying large infrastructures with many nodes and alerts.
**Format:** Integer (milliseconds)
**Default:** Server default timeout (typically 30000ms = 30 seconds)
**Examples:**
- `timeout=5000` - 5 second timeout
- `timeout=60000` - 60 second timeout
When the timeout is exceeded, the server returns a partial result with whatever data was collected before the timeout.
'
required: false
schema:
type: integer
format: int64
minimum: 1000
example: 30000
- name: cardinality
in: query
description: 'Limit the number of alert instances returned to prevent response explosion.
When monitoring large infrastructures, some alert types may have hundreds or thousands of instances (e.g., disk space alerts for every disk on every node).
This parameter limits the number of unique alert instances in the response.
**Format:** Integer (maximum number of alert instances)
**Default:** No limit
**Use Cases:**
- Preventing huge responses when there are many alert instances
- Getting a sample of alerts rather than complete list
- Dashboard widgets with limited display space
**Example:**
- `cardinality=100` - Return at most 100 alert instances
**Alias:** Can also be specified as `cardinality_limit`
When the limit is exceeded, the response may indicate how many alerts were omitted.
'
required: false
schema:
type: integer
minimum: 1
example: 100
responses:
'200':
description: 'Success. Returns current alert status information.
**Response Structure:**
- Summary counters (when options=summary): counts by status, type, classification
- Alert instances with their current states
- Alert values and thresholds (when options=values)
- Alert configurations (when options=configurations)
- Node and context associations
The response is grouped by contexts and includes metadata about each alert including its current status, value, time in current state, and associated chart/dimension.
**Response Characteristics:**
- JSON format
- Not cacheable (alerts change frequently)
- May include partial results if timeout is exceeded
- Cardinality-limited if specified
'
content:
application/json:
schema:
type: object
description: Multi-node alert status information
'400':
description: 'Bad request. Common causes:
- Invalid parameter values
- Malformed filter patterns
- Invalid status values
- Invalid timeout or cardinality values
'
'500':
description: Internal server error. Usually indicates the server is out of memory.
/api/v3/alert_transitions:
get:
operationId: alert_transitions_v3
tags:
- alerts
summary: Retrieve alert state transition history across all nodes with advanced filtering
description: 'Returns the historical record of alert state changes (transitions) across the monitored infrastructure. This endpoint provides detailed information about when alerts changed state (e.g., from CLEAR to WARNING to CRITICAL), allowing you to analyze alert patterns, investigate incidents, and understand system behavior over time.
**What is an Alert Transition?**
An alert transition is a record of an alert changing from one state to another. Each transition includes:
- Previous and new alert status (CLEAR, WARNING, CRITICAL, etc.)
- When the transition occurred
- How long the alert stayed in the previous state (duration)
- Alert value at the time of transition
- Complete alert metadata (name, context, node, etc.)
**Key Features:**
- **Multi-Node Support:** Query transitions across entire infrastructure
- **Advanced Filtering:** Filter by status, type, component, role, node, alert name, context
- **Faceted Search:** Use multiple filter facets simultaneously (e.g., "CRITICAL status on database nodes")
- **Pagination:** Navigate through large result sets using anchor_gi
- **Time Range:** Specify exact time windows for historical analysis
**Use Cases:**
- Incident investigation: "What alerts fired during the outage?"
- Alert pattern analysis: "How often does this alert transition to CRITICAL?"
- Alert tuning: "Which alerts flap between states most frequently?"
- Compliance reporting: "Show all CRITICAL alerts in the last 30 days"
- Root cause analysis: "What changed before this alert fired?"
**Faceted Filtering:**
This endpoint supports 9 different facets for precise filtering:
- f_status: Filter by alert status (CRITICAL, WARNING, etc.)
- f_type: Filter by alert type (e.g., "System", "Database", "Network")
- f_role: Filter by recipient role (who should be notified)
- f_class: Filter by alert classification
- f_component: Filter by system component
- f_node: Filter by specific node hostname
- f_alert: Filter by alert name
- f_instance: Filter by chart instance name
- f_context: Filter by metric context
**Examples:**
1. Recent critical transitions: `?last=100&f_status=CRITICAL`
2. Database alerts: `?f_component=Database&after=-86400`
3. Specific alert history: `?f_alert=disk_space_usage&last=50`
4. Node-specific transitions: `?f_node=web-server-01&after=-604800`
**Response Format:**
Returns a JSON array of transition records, ordered by time (newest first by default). Each record includes complete transition metadata, alert details, and timing information.
**Performance Considerations:**
- Use time ranges (after/before) to limit query scope
- Use cardinality limits for large result sets
- Timeout parameter prevents long-running queries
- Pagination via anchor_gi for processing large datasets
**Security & Access Control:**
- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply
- **Default Access:** Public (no authentication required)
- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token
- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf
- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools
'
security:
- {}
- bearerAuth: []
parameters:
- name: scope_nodes
in: query
description: 'Filter transitions to only include specific nodes using simple pattern matching.
This parameter defines which nodes to include in the search using Netdata''s simple pattern syntax (not regex).
**Pattern Syntax:**
- `*` matches any number of characters (including none)
- `node1 node2` space-separated list matches any of the nodes
- `!node3` exclude specific nodes (prefix with !)
- Can combine inclusion and exclusion: `web* !web-test*`
**Examples:**
- `scope_nodes=web*` - All nodes starting with "web"
- `scope_nodes=web* db*` - All web and database nodes
- `scope_nodes=* !test*` - All nodes except test nodes
- `scope_nodes=prod-web-01` - Specific node only
**Use Cases:**
- Focus on specific node groups (production vs staging)
- Exclude test/development nodes from analysis
- Investigate issues on specific infrastructure tiers
When not specified, transitions from all nodes are included.
'
required: false
schema:
type: string
examples:
all_web_nodes:
value: web*
summary: All web servers
prod_only:
value: '* !test* !dev*'
summary: Production nodes only
- name: nodes
in: query
description: 'Filter transitions to specific nodes by their exact names.
Unlike `scope_nodes` which supports patterns, this parameter requires exact node names. Multiple nodes are separated by comma or pipe.
**Format:** Comma or pipe-separated list of exact node names
**Examples:**
- `nodes=web-server-01` - Single specific node
- `nodes=web-server-01,web-server-02,db-server-01` - Multiple specific nodes
- `nodes=web-server-01|web-server-02` - Pipe separator also works
**Difference from scope_nodes:**
- `scope_nodes`: Pattern matching, filters at query time
- `nodes`: Exact names, more efficient for known node names
**Best Practice:** Use `nodes` when you know exact node names, use `scope_nodes` for pattern-based filtering.
When not specified, transitions from all nodes matching scope_nodes (or all nodes if scope_nodes is also not specified) are included.
'
required: false
schema:
type: string
example: web-server-01,db-server-01
- name: scope_contexts
in: query
description: 'Filter transitions to only include alerts from specific metric contexts using pattern matching.
Contexts group similar metrics across instances (e.g., `system.cpu` groups CPU metrics from all nodes, `disk.io` groups disk I/O from all disks).
**Pattern Syntax:**
- `*` matches any number of characters
- `context1 context2` space-separated list matches any of the contexts
- `!context3` exclude specific contexts
- Can combine: `system.* !system.io*`
**Common Context Patterns:**
- `system.*` - All system-level metrics
- `disk.*` - All disk-related metrics
- `net.*` - All network-related metrics
- `mysql.*` - All MySQL metrics
- `nginx.*` - All Nginx metrics
**Examples:**
- `scope_contexts=system.cpu` - Only CPU alerts
- `scope_contexts=disk.* net.*` - All disk and network alerts
- `scope_contexts=* !system.ip*` - All contexts except IP-related
**Use Cases:**
- Focus on specific subsystem (e.g., storage, network)
- Exclude noisy alert types
- Component-specific incident investigation
When not specified, transitions from all contexts are included.
'
required: false
schema:
type: string
examples:
disk_alerts:
value: disk.*
summary: All disk-related alerts
critical_systems:
value: system.* disk.* net.*
summary: System, disk, and network alerts
- name: contexts
in: query
description: 'Filter transitions to specific contexts by their exact names.
Unlike `scope_contexts` which supports patterns, this parameter requires exact context names.
**Format:** Comma or pipe-separated list of exact context names
**Examples:**
- `contexts=system.cpu` - Single specific context
- `contexts=system.cpu,system.load,system.ram` - Multiple contexts
- `contexts=disk.space|disk.inodes` - Pipe separator
**Difference from scope_contexts:**
- `scope_contexts`: Pattern matching for flexible filtering
- `contexts`: Exact names for precise filtering
When not specified, transitions from all contexts matching scope_contexts are included.
'
required: false
schema:
type: string
example: system.cpu,system.ram,disk.space
- name: alert
in: query
description: 'Filter transitions to a specific alert by its exact name.
Alert names are unique identifiers for specific alert configurations.
**Format:** Exact alert name (case-sensitive)
**Examples:**
- `alert=disk_space_usage` - Transitions for disk space alert
- `alert=cpu_usage` - Transitions for CPU usage alert
- `alert=ram_in_use` - Transitions for RAM usage alert
**Use Cases:**
- Analyze history of a specific alert
- Tune alert thresholds based on historical behavior
- Investigate alert flapping (rapid state changes)
- Track alert effectiveness
**Tip:** To find available alert names, query `/api/v3/alerts` first or use the `/api/v3/alert_config` endpoint.
When not specified, transitions for all alerts are included.
'
required: false
schema:
type: string
example: disk_space_usage
- name: transition
in: query
description: 'Filter to a specific transition by its unique identifier.
Each transition has a unique ID (UUID). This parameter is rarely used but can retrieve exact transition records.
**Format:** UUID string
**Use Case:** Retrieve exact transition details when you have the transition ID from another query or notification.
When not specified, all transitions matching other filters are included.
'
required: false
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440000
- name: last
in: query
description: 'Limit the number of transition records returned.
This controls how many transition records to include in the response, ordered by time (most recent first).
**Format:** Positive integer
**Default:** 1 (returns only the most recent transition)
**Examples:**
- `last=1` - Most recent transition only (default)
- `last=100` - Last 100 transitions
- `last=1000` - Last 1000 transitions
**Use Cases:**
- Dashboard widgets showing recent N alerts
- API clients with pagination
- Limiting response size for performance
**Pagination:**
For datasets larger than `last`, use the `anchor_gi` parameter to navigate to the next page:
1. Make request with `last=100`
2. Note the `global_id` of the last transition in response
3. Make next request with `last=100&anchor_gi=<global_id>`
**Performance Note:** Smaller values of `last` result in faster queries and smaller responses.
**IMPORTANT:** This parameter is required. If not specified, defaults to 1.
'
required: true
schema:
type: integer
minimum: 1
default: 1
example: 100
- name: anchor_gi
in: query
description: 'Global ID anchor for pagination through large result sets.
Each transition has a unique global_id (an incrementing number). Use this parameter to paginate through results by specifying the global_id of the last transition from the previous page.
**How Pagination Works:**
1. First request: `?last=100` - Returns first 100 transitions
2. Extract `global_id` of the 100th (last) transition from response
3. Next request: `?last=100&anchor_gi=<global_id>` - Returns next 100 transitions
**Format:** Positive integer (global_id from previous response)
**Examples:**
- `anchor_gi=12345` - Start from transition with global_id 12345
- Combined with last: `last=100&anchor_gi=12345` - Get 100 transitions starting after global_id 12345
**Use Cases:**
- Processing large alert history datasets
- Implementing "load more" in UIs
- Batch processing of transition records
- Exporting complete alert history
**Direction:**
- Results are ordered by global_id (which correlates with time)
- Anchor specifies "start after this ID"
- Each page contains `last` number of records
When not specified, pagination starts from the most recent transition.
'
required: false
schema:
type: integer
format: int64
minimum: 0
example: 12345678
- name: f_status
in: query
description: '**Facet Filter:** Filter transitions by their NEW status (the status the alert transitioned TO).
**Available Status Values:**
- `CRITICAL` - Alert in critical state (highest severity)
- `WARNING` - Alert in warning state
- `CLEAR` - Alert returned to normal state
- `UNDEFINED` - Alert evaluation failed (e.g., metric missing, division by zero)
- `UNINITIALIZED` - Alert not yet evaluated (no data yet)
- `REMOVED` - Alert was removed (plugin stopped, configuration changed)
**Format:** Comma-separated list of status values
**Examples:**
- `f_status=CRITICAL` - Only transitions TO critical state
- `f_status=CRITICAL,WARNING` - Transitions to critical or warning
- `f_status=CLEAR` - When alerts cleared (returned to normal)
**Use Cases:**
- Find when alerts became critical: `f_status=CRITICAL`
- Track alert recovery: `f_status=CLEAR`
- Find alert failures: `f_status=UNDEFINED`
- Incident timeline: `f_status=CRITICAL,WARNING`
**Note:** This filters by the NEW status. To see transitions FROM a status to another, you''ll need to examine the old_status field in the response.
When not specified, transitions to all statuses are included.
'
required: false
schema:
type: string
examples:
critical_only:
value: CRITICAL
summary: Only critical transitions
problems:
value: CRITICAL,WARNING
summary: Problem states
recoveries:
value: CLEAR
summary: Alert recoveries
- name: f_type
in: query
description: '**Facet Filter:** Filter transitions by alert type.
Alert types categorize alerts by what they monitor (e.g., "System", "Database", "Web Server").
**Format:** Comma-separated list of alert type names
**Common Alert Types:**
- `System` - System-level alerts (CPU, RAM, load)
- `Database` - Database monitoring alerts
- `Web Server` - Web server alerts (Nginx, Apache)
- `Network` - Network-related alerts
- `Storage` - Storage and disk alerts
**Examples:**
- `f_type=System` - Only system alerts
- `f_type=Database,Web Server` - Database and web server alerts
**Use Cases:**
- Focus on specific infrastructure component types
- Filter by technology stack (databases, web servers, etc.)
- Team-specific alert filtering
**Note:** The exact type values depend on your alert configurations. Query `/api/v3/alerts` to see available types in your installation.
When not specified, transitions of all types are included.
'
required: false
schema:
type: string
example: System,Database
- name: f_role
in: query
description: '**Facet Filter:** Filter transitions by recipient role.
Roles define who should be notified about alerts (e.g., "sysadmin", "dba", "webmaster").
**Format:** Comma-separated list of role names
**Common Roles:**
- `sysadmin` - System administrators
- `dba` - Database administrators
- `webmaster` - Web server administrators
- `devops` - DevOps team
- `security` - Security team
**Examples:**
- `f_role=sysadmin` - Alerts for sysadmin role
- `f_role=sysadmin,dba` - Alerts for sysadmins and DBAs
**Use Cases:**
- Team-specific alert filtering
- Role-based alert analysis
- Notification audit trails
**Note:** Roles are defined in your alert configurations. The exact role values depend on your Netdata setup.
When not specified, transitions for all roles are included.
'
required: false
schema:
type: string
example: sysadmin,dba
- name: f_class
in: query
description: '**Facet Filter:** Filter transitions by alert classification.
Alert classifications categorize alerts by their nature (e.g., "Errors", "Latency", "Utilization").
**Format:** Comma-separated list of classification names
**Common Classifications:**
- `Errors` - Error-related alerts
- `Latency` - Performance/latency alerts
- `Utilization` - Resource utilization alerts
- `Availability` - Availability/uptime alerts
- `Workload` - Workload-related alerts
**Examples:**
- `f_class=Errors` - Only error-related transitions
- `f_class=Latency,Utilization` - Performance and utilization alerts
**Use Cases:**
- Focus on specific problem categories
- SLA/SLO tracking by classification
- Alert categorization analysis
When not specified, transitions of all classifications are included.
'
required: false
schema:
type: string
example: Errors,Latency
- name: f_component
in: query
description: '**Facet Filter:** Filter transitions by system component.
Components identify which part of the system the alert relates to (e.g., "Network", "Disk", "Memory").
**Format:** Comma-separated list of component names
**Common Components:**
- `Network` - Network-related alerts
- `Disk` - Disk/storage alerts
- `Memory` - Memory alerts
- `CPU` - CPU alerts
- `Database` - Database component alerts
**Examples:**
- `f_component=Disk` - Only disk-related transitions
- `f_component=Network,Disk` - Network and disk alerts
**Use Cases:**
- Component-specific incident investigation
- Infrastructure subsystem analysis
- Capacity planning by component
When not specified, transitions for all components are included.
'
required: false
schema:
type: string
example: Disk,Network
- name: f_node
in: query
description: '**Facet Filter:** Filter transitions by exact node hostname.
This is a facet filter alternative to the `nodes` parameter, typically used when you want to combine it with other facets.
**Format:** Comma-separated list of exact node hostnames
**Examples:**
- `f_node=web-server-01` - Single specific node
- `f_node=web-server-01,db-server-01` - Multiple nodes
**Difference from `nodes` parameter:**
- Both accept exact node names
- `f_node` is a facet filter (can be combined with other f_* filters)
- `nodes` is a direct filter parameter
**Best Practice:** Use `nodes` for simple node filtering, use `f_node` when combining with other facets in complex queries.
When not specified, all nodes are included.
'
required: false
schema:
type: string
example: web-server-01
- name: f_alert
in: query
description: '**Facet Filter:** Filter transitions by exact alert name.
This is a facet filter alternative to the `alert` pa
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netdata/refs/heads/main/openapi/netdata-alerts-api-openapi.yml