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: \"\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: `__`\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=\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 ``` **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"