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 functions 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: functions
description: Everything related to functions
paths:
/api/v3/progress:
get:
operationId: progress3
tags:
- functions
summary: Track progress of long-running function executions
description: "Monitors the progress of long-running Netdata function executions identified by a transaction ID.\nWhen executing functions that may take significant time (e.g., data collection, analysis, exports),\nthis endpoint allows clients to poll for progress updates and track completion status.\n\n**Function Execution Flow:**\n1. Client initiates a function execution (e.g., via `/api/v3/function`)\n2. Function returns immediately with a transaction ID\n3. Client polls `/api/v3/progress?transaction=<id>` for status updates\n4. Progress endpoint returns completion percentage and status\n5. When complete, client retrieves final results\n\n**Progress Information Includes:**\n- **Percentage complete**: 0-100% progress indicator\n- **Status**: running, completed, failed, cancelled\n- **Message**: Human-readable status description\n- **Remaining time estimate**: If available\n\n**Use Cases:**\n- **Long data exports**: Track progress of large data export operations\n- **Analysis functions**: Monitor CPU-intensive analysis tasks\n- **Batch operations**: Track multi-step batch processing\n- **User experience**: Provide progress feedback in UI applications\n\n**Polling Best Practices:**\n- Poll every 1-2 seconds for responsive updates\n- Implement exponential backoff for completed/failed states\n- Set reasonable timeouts (functions may take minutes)\n- Handle cancellation gracefully\n\n**Common Usage Patterns:**\n\n1. **Poll for function progress:**\n ```\n /api/v3/progress?transaction=550e8400-e29b-41d4-a716-446655440000\n ```\n\n2. **Integration with function execution:**\n ```javascript\n // 1. Start function\n const response = await fetch('/api/v3/function?...');\n const { transaction } = await response.json();\n\n // 2. Poll for progress\n const interval = setInterval(async () => {\n const progress = await fetch(`/api/v3/progress?transaction=${transaction}`);\n const { percentage, status } = await progress.json();\n\n if (status === 'completed') {\n clearInterval(interval);\n // Fetch final results\n }\n }, 1000);\n ```\n\n**Transaction ID Format:**\n- UUID v4 format: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`\n- Returned by function execution endpoints\n- Valid for the lifetime of the function execution\n- Expires after completion or timeout\n\n**Security & Access Control:**\n- \U0001F513 **Always Public API** - This endpoint is always accessible without authentication\n- **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions\n- **No Authentication:** Cannot be restricted by any configuration\n- **Access:** Available to anyone who can reach the agent's HTTP endpoint\n"
parameters:
- name: transaction
in: query
required: true
description: 'Transaction ID (UUID) of the function execution to track. This ID is returned
when initiating a function execution via `/api/v3/function` or similar endpoints.
**UUID Format:**
- Standard UUID v4 format
- Example: `550e8400-e29b-41d4-a716-446655440000`
- Case-insensitive
**Transaction Lifecycle:**
- **Created**: When function execution starts
- **Active**: While function is running
- **Expired**: After completion, failure, or timeout
- **Retention**: Transaction state kept briefly after completion for final status retrieval
**Invalid Transaction Handling:**
- Missing transaction: Returns 400 Bad Request
- Malformed UUID: Returns 400 Bad Request
- Expired transaction: Returns 404 Not Found
- Unknown transaction: Returns 404 Not Found
'
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: 'Successfully retrieved progress information for the transaction.
Returns current progress status including percentage complete, state, and optional message.
'
content:
application/json:
schema:
type: object
properties:
transaction:
type: string
format: uuid
description: The transaction ID being tracked
status:
type: string
enum:
- running
- completed
- failed
- cancelled
description: Current status of the function execution
percentage:
type: integer
minimum: 0
maximum: 100
description: Completion percentage (0-100)
message:
type: string
description: Human-readable status message or error description
done:
type: integer
description: Number of items processed (if applicable)
all:
type: integer
description: Total number of items to process (if applicable)
eta_seconds:
type: integer
description: Estimated time remaining in seconds (if available)
examples:
running:
value:
transaction: 550e8400-e29b-41d4-a716-446655440000
status: running
percentage: 45
message: Processing data...
done: 450
all: 1000
eta_seconds: 30
completed:
value:
transaction: 550e8400-e29b-41d4-a716-446655440000
status: completed
percentage: 100
message: Function execution completed successfully
failed:
value:
transaction: 550e8400-e29b-41d4-a716-446655440000
status: failed
percentage: 67
message: 'Error: timeout during data collection'
'400':
description: 'Bad request. Common causes:
- Missing transaction parameter
- Malformed UUID format
- Invalid transaction ID format
'
'404':
description: 'Transaction not found. Possible reasons:
- Transaction ID does not exist
- Transaction has expired (completed/failed long ago)
- Transaction was never created
'
'500':
description: Internal server error during progress tracking.
/api/v3/function:
get:
operationId: function3
tags:
- functions
summary: Execute a Netdata function on a specific node
description: "Executes a named function on a Netdata agent to retrieve live information or trigger actions.\nFunctions are plugin-provided operations that can query system state, collect real-time data,\nor perform administrative tasks.\n\n**What are Netdata Functions?**\nFunctions extend Netdata beyond passive metric collection by allowing:\n- **Live data queries**: Get current system state (processes, connections, services)\n- **Interactive diagnostics**: Run on-demand checks and analysis\n- **Administrative operations**: Trigger actions like cache clearing or config reloading\n- **Plugin-specific features**: Access specialized capabilities provided by plugins\n\n**Common Functions Include:**\n- `systemd-list-units` - List systemd services and their status\n- `processes` - List currently running processes with resource usage\n- `network-connections` - Show active network connections\n- `mount-points` - Display mounted filesystems\n- `docker-containers` - List Docker containers (if Docker plugin enabled)\n- Many more plugin-specific functions\n\n**Function Discovery:**\nUse `/api/v3/functions` to discover available functions on each node.\n\n**Execution Model:**\n- Functions execute on the target node's agent\n- Results are collected and returned in real-time\n- Long-running functions return a transaction ID for progress tracking\n- Functions may require specific permissions or capabilities\n\n**Use Cases:**\n- **System diagnostics**: Query live system state for troubleshooting\n- **Capacity planning**: Get current resource utilization details\n- **Security auditing**: List processes, connections, open ports\n- **Service management**: Check service status across infrastructure\n- **Interactive dashboards**: Provide drill-down capabilities\n\n**Common Usage Patterns:**\n\n1. **List running processes:**\n ```\n /api/v3/function?function=processes\n ```\n\n2. **List systemd services:**\n ```\n /api/v3/function?function=systemd-list-units&timeout=30\n ```\n\n3. **Get network connections:**\n ```\n /api/v3/function?function=network-connections\n ```\n\n4. **Execute with custom timeout for slow operations:**\n ```\n /api/v3/function?function=docker-containers&timeout=60\n ```\n\n**Function Response Formats:**\n- Most functions return JSON data\n- Some may return plain text or formatted output\n- Check Content-Type header for response format\n- Long operations may return transaction ID for `/api/v3/progress` polling\n\n**Security Considerations:**\n- Functions respect user authentication and authorization\n- Some functions may require elevated permissions\n- Function execution is subject to ACL checks\n- Sensitive operations may be restricted by configuration\n\n**Security & Access Control:**\n- \U0001F4CA **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token\n- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf\n- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools\n"
security:
- {}
- bearerAuth: []
parameters:
- name: function
in: query
required: true
description: 'Name of the function to execute. Each Netdata plugin can provide multiple functions
with different capabilities.
**Function Names:**
- Kebab-case naming: `function-name-here`
- Provided by plugins: different plugins provide different functions
- Discoverable via `/api/v3/functions` endpoint
- Case-sensitive
**Common Built-in Functions:**
- `systemd-list-units` - List systemd services
- `processes` - Running processes with CPU/memory usage
- `network-connections` - Active network connections and sockets
- `mount-points` - Mounted filesystems and usage
- `ipmi-sensors` - IPMI hardware sensors (if available)
**Plugin-Specific Functions:**
- Docker plugin: `docker-containers`, `docker-images`
- Apps plugin: `apps-processes`
- Logs plugin: `logs-query`
- And many more depending on enabled plugins
**Invalid Function Names:**
- Missing function: Returns 400 Bad Request
- Unknown function: Returns 404 Not Found or function-specific error
- Disabled function: Returns 403 Forbidden
'
schema:
type: string
example: processes
- name: timeout
in: query
required: false
description: "Maximum time in seconds to wait for function execution before timing out.\nDifferent functions have different execution times.\n\n**Timeout Guidelines by Function Type:**\n- **Fast queries** (< 1s): processes, mount-points\n Recommended: 10-30 seconds\n- **Medium queries** (1-5s): systemd-list-units, network-connections\n Recommended: 30-60 seconds\n- **Slow operations** (5-30s): docker operations, log queries\n Recommended: 60-300 seconds\n\n**Timeout Behavior:**\n- If execution completes before timeout: Returns results immediately\n- If timeout expires: Function is cancelled and error returned\n- For async functions: Returns transaction ID immediately, timeout applies to overall operation\n\n**Best Practices:**\n- Set conservative timeouts for production systems\n- Consider network latency for remote nodes\n- Monitor timeout errors and adjust accordingly\n"
schema:
type: integer
minimum: 1
maximum: 3600
default: 60
example: 30
responses:
'200':
description: 'Function executed successfully and returned results.
The response format depends on the specific function:
- Most functions return JSON data
- Some return plain text or formatted output
- Check Content-Type header
'
content:
application/json:
schema:
type: object
description: Function-specific response data
examples:
processes:
value:
processes:
- pid: 1234
name: nginx
cpu: 2.5
memory: 45678
- pid: 5678
name: postgres
cpu: 15.3
memory: 234567
systemd_units:
value:
units:
- name: nginx.service
state: active
substate: running
- name: postgresql.service
state: active
substate: running
text/plain:
schema:
type: string
description: Plain text response from function
'202':
description: 'Function execution started asynchronously. Use the returned transaction ID
to poll `/api/v3/progress` for status and results.
'
content:
application/json:
schema:
type: object
properties:
transaction:
type: string
format: uuid
description: Transaction ID for progress tracking
message:
type: string
description: Status message
'400':
description: 'Bad request. Common causes:
- Missing required `function` parameter
- Invalid function name format
- Invalid request body for the function
'
'403':
description: 'Forbidden. Possible reasons:
- Function requires higher permissions than current user has
- Function is disabled in configuration
- ACL restrictions prevent execution
'
'404':
description: 'Function not found. The specified function does not exist or is not available on this node.
'
'500':
description: Internal server error during function execution.
'503':
description: 'Service unavailable. Netdata agent is not ready or function execution system is overloaded.
'
'504':
description: Function execution timeout - operation took longer than specified timeout.
post:
operationId: function3_post
tags:
- functions
summary: Execute a Netdata function with request body parameters
description: 'Same as GET /api/v3/function, but allows passing parameters via request body for functions
that require complex input or configuration data.
Use this method when:
- Function requires complex parameters that don''t fit in query string
- Passing sensitive data that shouldn''t be in URL
- Function accepts JSON configuration or structured data
See GET /api/v3/function for complete documentation on functions, timeouts, and responses.
'
security:
- {}
- bearerAuth: []
parameters:
- name: function
in: query
required: true
description: Name of the function to execute (see GET method for details)
schema:
type: string
example: processes
- name: timeout
in: query
required: false
description: Maximum time in seconds to wait for function execution (see GET method for details)
schema:
type: integer
minimum: 1
maximum: 3600
default: 60
example: 30
requestBody:
description: "Optional request body for functions that accept parameters or configuration.\nThe format and content depend on the specific function being executed.\n\n**When to Use Request Body:**\n- Functions that accept filtering parameters\n- Functions that need configuration data\n- Functions with complex input requirements\n\n**Common Patterns:**\n- JSON object with function-specific parameters\n- Plain text for simple commands\n- Format specified by function documentation\n\n**Example for logs-query function:**\n```json\n{\n \"after\": -3600,\n \"before\": 0,\n \"filter\": \"error\",\n \"limit\": 100\n}\n```\n"
required: false
content:
application/json:
schema:
type: object
description: Function-specific parameters (varies by function)
text/plain:
schema:
type: string
description: Plain text parameters for simple functions
responses:
'200':
description: Function executed successfully (see GET method for response details)
content:
application/json:
schema:
type: object
text/plain:
schema:
type: string
'202':
description: Function execution started asynchronously (see GET method for details)
'400':
description: Bad request (see GET method for details)
'403':
description: Forbidden (see GET method for details)
'404':
description: Function not found (see GET method for details)
'500':
description: Internal server error (see GET method for details)
'503':
description: Service unavailable (see GET method for details)
'504':
description: Function execution timeout (see GET method for details)
/api/v3/functions:
get:
operationId: functions3
tags:
- functions
summary: List available functions across all nodes
description: "Retrieves a catalog of available functions across the monitored infrastructure.\nFunctions are plugin-provided operations that extend Netdata's capabilities beyond\npassive metric collection, allowing live queries, diagnostics, and administrative actions.\n\n**What This Endpoint Returns:**\n- **Function inventory**: All functions available across your nodes\n- **Per-node availability**: Which functions each node supports\n- **Function metadata**: Descriptions, parameters, requirements\n- **Plugin information**: Which plugin provides each function\n\n**Function Categories:**\n- **System queries**: processes, mount-points, network-connections\n- **Service management**: systemd-list-units, docker-containers\n- **Hardware**: ipmi-sensors, smart-disk-info\n- **Application-specific**: mysql-queries, redis-info, nginx-status\n- **Diagnostics**: performance-analysis, log-queries\n- **Administrative**: config-reload, cache-clear\n\n**Use Cases:**\n- **Capability discovery**: Determine what operations are available\n- **Multi-node comparison**: See which nodes support which functions\n- **Plugin verification**: Confirm plugins are loaded and functional\n- **UI generation**: Build dynamic interfaces based on available functions\n- **Documentation**: Generate function reference for your infrastructure\n\n**Common Usage Patterns:**\n\n1. **List all functions across all nodes:**\n ```\n /api/v3/functions\n ```\n\n2. **Functions for specific nodes:**\n ```\n /api/v3/functions?nodes=web-*\n ```\n\n3. **Scope to production infrastructure:**\n ```\n /api/v3/functions?scope_nodes=prod-*\n ```\n\n4. **Get detailed function information:**\n ```\n /api/v3/functions?options=debug\n ```\n\n**Response Organization:**\nResults grouped by:\n- **Node**: Functions available on each node\n- **Function name**: Unique identifier\n- **Plugin**: Source plugin providing the function\n- **Capabilities**: What the function can do\n\n**Integration with /api/v3/function:**\n1. Use `/api/v3/functions` to discover available functions\n2. Use `/api/v3/function?function=<name>` to execute specific functions\n3. Results tell you which nodes support which operations\n\n**Security & Access Control:**\n- \U0001F4CA **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token\n- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf\n- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools\n"
security:
- {}
- bearerAuth: []
parameters:
- name: scope_nodes
in: query
required: false
description: 'Simple pattern to match node hostnames for scope filtering. Uses Netdata''s simple pattern
matching (not regex). Matched nodes define the scope for function discovery.
**Pattern Syntax:**
- `*` matches any number of characters
- Use `|` to separate multiple patterns (OR logic)
- Matches are case-insensitive
- No regex support - only simple wildcards
**Examples:**
- `prod-*` - All production nodes
- `*-web-*` - All web server nodes
- `db-*|cache-*` - All database or cache nodes
- `*` - All nodes (default)
'
schema:
type: string
default: '*'
example: prod-*
- name: nodes
in: query
required: false
description: 'Simple pattern to filter which nodes to include in the functions list.
After scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes.
**Difference from scope_nodes:**
- `scope_nodes` defines what nodes to query for functions
- `nodes` filters which nodes appear in the output
**Examples:**
- `web-*` - Only show functions from web servers
- Specific hostnames: `node1|node2|node3`
'
schema:
type: string
default: '*'
example: '*'
- name: options
in: query
required: false
description: 'Comma-separated list of options to control response content and format.
**Available Options:**
- `minify` - Minimize JSON output (no pretty-printing)
- `debug` - Include detailed function metadata and plugin information
- `raw` - Include raw function definitions
**Examples:**
- `minify` - Compact JSON response
- `debug,raw` - Full debug information
'
schema:
type: string
example: debug
- name: timeout
in: query
required: false
description: 'Maximum time in seconds to wait for the query to complete before timing out.
**Guidelines:**
- Recommended: 10-30 seconds for most queries
- Function listing is usually fast
- Timeout mainly applies to very large infrastructures
'
schema:
type: integer
minimum: 1
default: 60
example: 10
- name: cardinality
in: query
required: false
description: 'Maximum number of nodes to include in the response to prevent overwhelming large responses.
When this limit is exceeded, the response will indicate how many nodes were omitted.
**Purpose:**
- Prevent memory exhaustion from very large infrastructures
- Control response size for performance
- Useful when exploring large node sets incrementally
**Recommendations:**
- Small infrastructures (< 100 nodes): Use default
- Medium infrastructures (100-1000 nodes): 500-1000
- Large infrastructures (> 1000 nodes): Use filtering or increase limit carefully
'
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
example: 500
responses:
'200':
description: 'Successfully retrieved functions catalog.
Returns available functions organized by node, with metadata about each function
including name, description, plugin source, and parameter requirements.
'
content:
application/json:
schema:
type: object
properties:
nodes:
type: array
description: Array of nodes with their available functions
items:
type: object
properties:
hostname:
type: string
description: Node hostname
machine_guid:
type: string
description: Unique node identifier
functions:
type: array
description: Functions available on this node
items:
type: object
properties:
name:
type: string
description: Function name
example: processes
plugin:
type: string
description: Plugin providing this function
example: apps.plugin
description:
type: string
description: Human-readable function description
parameters:
type: array
description: Required or optional parameters
items:
type: object
properties:
name:
type: string
required:
type: boolean
description:
type: string
omitted:
type: integer
description: Number of nodes omitted due to cardinality limit
examples:
functions_list:
value:
nodes:
- hostname: web-server-1
machine_guid: 12345678-1234-1234-1234-123456789012
functions:
- name: processes
plugin: apps.plugin
description: List running processes with resource usage
- name: systemd-list-units
plugin: systemd.plugin
description: List systemd services and their status
- name: network-connections
plugin: network.plugin
description: Show active network connections
'400':
description: Invalid parameters provided (e.g., invalid pattern syntax).
'500':
description: Internal server error during functions listing.
'504':
description: Query timeout - functions collection took too long.
/api/v2/progress:
get:
deprecated: true
operationId: progress2
tags:
- functions
summary: 'OBSOLETE: Track async operation progress (use /api/v3/progress instead)'
description: '**⚠️ OBSOLETE API - Will be removed in future versions**
This endpoint is deprecated. Use `/api/v3/progress` instead, which provides the same functionality.
**Migration:** Replace `/api/v2/progress` with `/api/v3/progress` in all API calls.
Tracks progress of long-running asynchronous operations using transaction UUID.
Used for polling function execution status and completion percentage.
**Security & Access Control:**
- 🔓 **Always Public API** - This endpoint is always accessible without authentication
- **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions
- **No Authentication:** Cannot be restricted by any configuration
- **Access:** Available to anyone who can reach the agent''s HTTP endpoint
'
parameters:
- name: transaction
in: query
required: true
schema:
type: string
format: uuid
description: Transaction UUID from async operation
responses:
'200':
description: Progress information successfully retrieved
'400':
description: Missing or invalid transaction parameter
/api/v2/functions:
get:
deprecated: true
operationId: functions2
tags:
- functions
summary: 'OBSOLETE: List available functions (use /api/v3/functions instead)'
description: '**⚠️ OBSOLETE API - Will be removed in future versions**
This endpoint is deprecated. Use `/api/v3/functions` instead, which provides the same functionality.
**Migrati
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netdata/refs/heads/main/openapi/netdata-functions-api-openapi.yml