The variables API from Netdata — 1 operation(s) for variables.
openapi: 3.0.0
info:
title: Netdata agent variables 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: variables
paths:
/api/v3/variable:
get:
operationId: variable_v3
tags:
- variables
summary: Retrieve the value of a specific chart variable used in alert expressions
description: 'Returns the current value of a variable associated with a specific chart. Variables are used in alert expressions for dynamic threshold calculations, data transformations, and alert logic evaluation.
**What are Chart Variables?**
Variables in Netdata are named values that can be:
- **Chart-specific metrics:** Current values from dimensions (e.g., `$used`, `$total`)
- **Calculated values:** Derived from chart data (e.g., percentages, ratios)
- **Statistical values:** Min, max, average values over time windows
- **Alert-related values:** Previous alert states, thresholds
- **System variables:** Host labels, node information
**Common Use Cases:**
- **Alert Threshold Debugging:** Understand what value triggered an alert
- **Alert Expression Development:** Test variable values while writing alert expressions
- **Troubleshooting:** Verify variable calculations are correct
- **Dynamic Configuration:** Check runtime values used in alert logic
**Variable Types:**
1. **Dimension Variables:** Direct dimension values (e.g., `used`, `free`, `cached`)
2. **Lookup Variables:** Result of lookup operations over time ranges
3. **Calculated Variables:** Custom calculations defined in alert configs
4. **Chart Variables:** Chart-level metadata (family, units, etc.)
5. **Host Variables:** Host-specific values and labels
**Example Variables:**
- `$this` - The current calculated value
- `$used` - Value of "used" dimension
- `$total` - Value of "total" dimension
- `$1hour_cpu_usage` - CPU usage over last hour (lookup variable)
- `$ram_percentage` - Calculated RAM usage percentage
**How Variables Work in Alerts:**
Alert expressions like `$this > 80` use variables to dynamically evaluate conditions. This endpoint lets you see the actual runtime values of these variables.
**Workflow for Alert Development:**
1. Identify the chart: `GET /api/v1/charts` or `GET /api/v3/contexts`
2. Get variable value: `GET /api/v3/variable?chart=system.ram&variable=$used`
3. Test alert expression with actual values
4. Refine alert thresholds based on variable behavior
**Response Format:**
Returns JSON with the variable value and metadata about how it was calculated, including:
- Current value
- Calculation trace (how the value was computed)
- Source dimensions
- Any transformations applied
**Note:** This is a specialized endpoint primarily used for alert development and troubleshooting. For general metric values, use `/api/v3/data` instead.
**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: chart
in: query
description: "The chart identifier (ID or name) where the variable is defined.\n\n**Chart Identifier Format:**\nCharts can be specified by either their unique ID or their name.\n\n**Chart ID Format:**\n- Format: `type.name` (e.g., `system.cpu`, `disk.sda_io`, `mysql.queries`)\n- This is the canonical identifier shown in chart metadata\n- Case-sensitive\n- More reliable as it doesn't change\n\n**Chart Name Format:**\n- Human-readable name (e.g., \"System CPU\")\n- May contain spaces\n- Less reliable as it can change\n- The API will try to find by name if ID lookup fails\n\n**How to Find Chart IDs:**\n1. **From /api/v1/charts:**\n ```\n GET /api/v1/charts\n ```\n Response includes all chart IDs in the system\n\n2. **From /api/v3/contexts:**\n ```\n GET /api/v3/contexts\n ```\n Lists contexts and their chart instances\n\n3. **From Alert Configuration:**\n Alert configs reference charts in their `on` clause\n\n4. **From Netdata Dashboard:**\n Chart IDs are shown in chart metadata\n\n**Examples:**\n- `chart=system.cpu` - System CPU chart\n- `chart=system.ram` - System RAM chart\n- `chart=disk.sda_io` - Disk sda I/O chart\n- `chart=mysql.queries` - MySQL queries chart\n\n**Common Chart IDs by Category:**\n- **System:** `system.cpu`, `system.load`, `system.ram`, `system.io`\n- **Disk:** `disk.space`, `disk.io`, `disk.inodes`\n- **Network:** `net.eth0`, `net.packets`\n- **Databases:** `mysql.queries`, `postgres.connections`, `redis.memory`\n\n**Important Notes:**\n- This parameter is **REQUIRED**\n- Must reference an existing chart on the specified host\n- Chart must be actively collecting data\n- Case-sensitive\n\n**Error Handling:**\n- Missing parameter → 400 Bad Request: \"A chart= and a variable= are required.\"\n- Invalid/non-existent chart → 404 Not Found: \"Chart is not found: <chart>\"\n"
required: true
schema:
type: string
examples:
system_ram:
value: system.ram
summary: System RAM chart
disk_space:
value: disk.space
summary: Disk space chart
mysql:
value: mysql.queries
summary: MySQL queries chart
- name: variable
in: query
description: "The variable name to look up within the specified chart.\n\n**Variable Name Format:**\nVariable names typically follow these conventions:\n- Start with `$` in alert expressions, but the `$` is optional in this parameter\n- Names are case-sensitive\n- Can reference dimensions, calculated values, or lookups\n\n**Variable Name Categories:**\n\n**1. Dimension Variables (most common):**\nDirect references to chart dimensions:\n- `used` - Value of \"used\" dimension\n- `free` - Value of \"free\" dimension\n- `cached` - Value of \"cached\" dimension\n- `buffers` - Value of \"buffers\" dimension\n- `read` - Read operations/bytes\n- `write` - Write operations/bytes\n\n**2. Special Variables:**\n- `this` - The calculated/evaluated value from alert expression\n- `status` - Current alert status\n- `value` - Current metric value\n\n**3. Lookup Variables:**\nVariables created via lookup operations:\n- Format: `<duration>_<dimension>_<method>`\n- Example: `1hour_cpu_avg` - Average CPU over last hour\n- Example: `5min_disk_used_max` - Max disk used in last 5 minutes\n\n**4. Calculated Variables:**\nCustom variables defined in alert configurations:\n- `ram_percentage` - (used / total) * 100\n- `disk_usage_ratio` - used / total\n- `error_rate` - errors / total_requests\n\n**5. Chart Metadata Variables:**\n- `family` - Chart family/category\n- `units` - Chart units\n- `chart_type` - Chart type\n\n**How to Discover Available Variables:**\n1. **From Alert Configuration:**\n Alert expressions reveal which variables are available\n ```\n GET /api/v3/alert_config?config=<uuid>\n ```\n\n2. **From /api/v1/alarm_variables:**\n Lists all variables for a chart\n ```\n GET /api/v1/alarm_variables?chart=system.ram\n ```\n\n3. **From Chart Dimensions:**\n Dimension names are typically available as variables\n ```\n GET /api/v1/chart?chart=system.ram\n ```\n\n**Common Variable Examples by Chart:**\n\n**For system.ram:**\n- `used`, `free`, `cached`, `buffers`\n\n**For system.cpu:**\n- `user`, `system`, `nice`, `idle`, `iowait`\n\n**For disk.space:**\n- `used`, `avail` (available), `reserved`\n\n**For disk.io:**\n- `read`, `write`\n\n**For mysql.queries:**\n- `select`, `insert`, `update`, `delete`\n\n**Important Notes:**\n- This parameter is **REQUIRED**\n- Variable name must exist in the chart's variable set\n- Case-sensitive\n- The `$` prefix is optional (both `$used` and `used` work)\n\n**Error Handling:**\n- Missing parameter → 400 Bad Request: \"A chart= and a variable= are required.\"\n- Non-existent variable → Returns trace showing variable not found\n"
required: true
schema:
type: string
examples:
dimension_value:
value: used
summary: Get 'used' dimension value
with_dollar:
value: $used
summary: Variable with $ prefix (equivalent)
special_variable:
value: this
summary: Current calculated value
responses:
'200':
description: "Success. Returns the variable value and calculation trace.\n\n**Response Structure:**\nThe response is a JSON object containing:\n\n**Variable Lookup Trace:**\nShows the step-by-step process of how the variable value was calculated:\n- Variable name being looked up\n- Source dimensions queried\n- Calculation methods applied\n- Intermediate values\n- Final calculated value\n\n**Example Response:**\n```json\n{\n \"variable\": \"$used\",\n \"chart\": \"system.ram\",\n \"value\": 8589934592,\n \"units\": \"B\",\n \"trace\": [\n {\n \"step\": \"lookup_dimension\",\n \"dimension\": \"used\",\n \"raw_value\": 8589934592\n },\n {\n \"step\": \"final_value\",\n \"value\": 8589934592,\n \"units\": \"B\"\n }\n ]\n}\n```\n\n**Response Fields:**\n- `variable`: The requested variable name\n- `chart`: The chart ID where variable was found\n- `value`: Current numeric value of the variable\n- `units`: Unit of measurement\n- `trace`: Array of calculation steps showing how value was derived\n\n**Trace Information:**\nThe trace provides transparency into variable evaluation, showing:\n- Dimension lookups performed\n- Data aggregation methods used\n- Time ranges evaluated\n- Transformations applied\n- Why certain values were selected\n\n**Use Cases for Trace:**\n- **Debugging Alerts:** Understand why an alert triggered\n- **Validating Logic:** Verify alert expressions evaluate correctly\n- **Performance Analysis:** See which dimensions contribute to variable\n- **Education:** Learn how alert variables are calculated\n\n**Response Characteristics:**\n- Content-Type: application/json\n- Not cacheable (values change constantly)\n- Real-time evaluation at query time\n- Includes calculation metadata\n\n**Note:** The exact trace format depends on the complexity of the variable lookup. Simple dimension variables have short traces, while complex calculated variables or lookups have detailed multi-step traces.\n"
content:
application/json:
schema:
type: object
description: Variable value and calculation trace
'400':
description: 'Bad request. Common causes:
- Missing `chart` parameter (error: "A chart= and a variable= are required.")
- Missing `variable` parameter (error: "A chart= and a variable= are required.")
- Empty parameter values
- Malformed request
**Error Response:**
Returns plain text error message explaining what went wrong.
**Example Error:**
```
A chart= and a variable= are required.
```
'
'404':
description: 'Chart not found. The specified chart ID or name does not exist.
**Error Response:**
Returns plain text message indicating chart was not found.
**Example Error:**
```
Chart is not found: system.nonexistent
```
**Common Reasons:**
- Chart ID was mistyped
- Chart doesn''t exist on this host
- Chart was removed (plugin stopped collecting)
- Chart is on a different node (check node parameter if in multi-node setup)
**Troubleshooting:**
1. List available charts: `GET /api/v1/charts`
2. Verify chart ID spelling and capitalization
3. Check if chart is actively collecting data
4. Ensure you''re querying the correct node
'
'500':
description: Internal server error during variable lookup.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Bearer token authentication for API access when bearer protection is enabled.
**How to obtain a token:**
1. Token must be obtained via `/api/v3/bearer_get_token` endpoint
2. This endpoint is ACLK-only (requires Netdata Cloud access)
3. Token includes role-based access control and expiration time
**How to use:**
```
Authorization: Bearer <token>
```
**When required:**
- When bearer protection is enabled on the agent (via `/api/v3/bearer_protection`)
- Applies to all APIs with `HTTP_ACCESS_ANONYMOUS_DATA` permission
- Does not apply to APIs with `HTTP_ACL_NOCHECK` (always public)
- Does not apply to ACLK-only APIs (use cloud authentication)
**Token expiration:**
- Tokens are time-limited and must be renewed periodically
- Expired tokens return HTTP 401 Unauthorized
'
aclkAuth:
type: http
scheme: bearer
description: 'ACLK-only authentication - these APIs are ONLY accessible via Netdata Cloud (ACLK).
**Access Requirements:**
- User must be authenticated via Netdata Cloud (`SIGNED_ID`)
- User and agent must be in the same Netdata Cloud space (`SAME_SPACE`)
- Additional role-based permissions may apply per endpoint
**NOT accessible via:**
- Direct HTTP/HTTPS to agent (even with bearer token)
- Local dashboard
- External integrations
**Available only through:**
- Netdata Cloud web interface
- Netdata Cloud API (ACLK tunnel)
**Development mode:**
- Can be made available in dev mode with `ACL_DEV_OPEN_ACCESS` flag
'
ipAcl:
type: apiKey
in: header
name: X-Forwarded-For
description: "IP-based Access Control List restrictions (informational only).\n\n**Configuration:**\nAPIs are subject to IP-based ACL restrictions configured in `netdata.conf`:\n\n```conf\n[web]\n allow dashboard from = *\n allow badges from = *\n allow management from = localhost\n```\n\n**ACL Categories:**\n- `allow dashboard from` - Controls access to metrics, alerts, nodes, functions, config APIs\n- `allow badges from` - Controls access to badge generation APIs\n- `allow management from` - Controls access to management APIs\n\n**Default behavior:**\n- Most APIs allow access from any IP by default\n- Management APIs restrict to localhost by default\n- Can be customized per deployment\n\n**Note:** This is not a standard authentication mechanism but rather IP filtering.\nAPIs with `HTTP_ACL_NOCHECK` bypass all IP restrictions.\n"