{ "opencollection": "1.0.0", "info": { "name": "Netdata agent functions API", "version": "v1-rolling" }, "items": [ { "info": { "name": "functions", "type": "folder" }, "items": [ { "info": { "name": "Track progress of long-running function executions", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v3/progress", "params": [ { "name": "transaction", "value": "550e8400-e29b-41d4-a716-446655440000", "type": "query", "description": "Transaction ID (UUID) of the function execution to track. This ID is returned\nwhen initiating a function execution via `/api/v3/function` or similar endpoints.\n\n**UUID Format:**\n- Standard UUID v4 format\n- Example: `550e8400-e29b-41d4-a716-446655440000`\n- Case-insensitive\n\n**Transaction Lifecycle:**\n- **Created**: When function execution starts\n- **Active**: While function is running\n- **Expired**: After completion, failure, or timeout\n- **Retention**: Transaction state kept briefly after completion for final status retrieval\n\n**Invalid Transaction Handling:**\n- Missing transaction: Returns 400 Bad Request\n- Malformed UUID: Returns 400 Bad Request\n- Expired transaction: Returns 404 Not Found\n- Unknown transaction: Returns 404 Not Found\n" } ] }, "docs": "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=` for sta" }, { "info": { "name": "Execute a Netdata function on a specific node", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v3/function", "params": [ { "name": "function", "value": "processes", "type": "query", "description": "Name of the function to execute. Each Netdata plugin can provide multiple functions\nwith different capabilities.\n\n**Function Names:**\n- Kebab-case naming: `function-name-here`\n- Provided by plugins: different plugins provide different functions\n- Discoverable via `/api/v3/functions` endpoint\n- Case-sensitive\n\n**Common Built-in Functions:**\n- `systemd-list-units` - List systemd services\n- `processes` - Running processes with CPU/memory usage\n- `network-connections` - Active network connections and sockets\n- `mount-points` - Mounted filesystems and usage\n- `ipmi-sensors` - IPMI hardware sensors (if available)\n\n**Plugin-Specific Functions:**\n- Docker plugin: `docker-containers`, `docker-images`\n- Apps plugin: `apps-processes`\n- Logs plugin: `logs-query`\n- And many more depending on enabled plugins\n\n**Invalid Function Names:**\n- Missing function: Returns 400 Bad Request\n- Unknown function: Returns 404 Not Found or function-specific error\n- Disabled function: Returns 403 Forbidden\n" }, { "name": "timeout", "value": "30", "type": "query", "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" } ] }, "docs": "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 operat" }, { "info": { "name": "Execute a Netdata function with request body parameters", "type": "http" }, "http": { "method": "POST", "url": "https://registry.my-netdata.io/api/v3/function", "params": [ { "name": "function", "value": "processes", "type": "query", "description": "Name of the function to execute (see GET method for details)" }, { "name": "timeout", "value": "30", "type": "query", "description": "Maximum time in seconds to wait for function execution (see GET method for details)" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Same as GET /api/v3/function, but allows passing parameters via request body for functions\nthat require complex input or configuration data.\n\nUse this method when:\n- Function requires complex parameters that don't fit in query string\n- Passing sensitive data that shouldn't be in URL\n- Function accepts JSON configuration or structured data\n\nSee GET /api/v3/function for complete documentation on functions, timeouts, and responses.\n" }, { "info": { "name": "List available functions across all nodes", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v3/functions", "params": [ { "name": "scope_nodes", "value": "prod-*", "type": "query", "description": "Simple pattern to match node hostnames for scope filtering. Uses Netdata's simple pattern\nmatching (not regex). Matched nodes define the scope for function discovery.\n\n**Pattern Syntax:**\n- `*` matches any number of characters\n- Use `|` to separate multiple patterns (OR logic)\n- Matches are case-insensitive\n- No regex support - only simple wildcards\n\n**Examples:**\n- `prod-*` - All production nodes\n- `*-web-*` - All web server nodes\n- `db-*|cache-*` - All database or cache nodes\n- `*` - All nodes (default)\n" }, { "name": "nodes", "value": "*", "type": "query", "description": "Simple pattern to filter which nodes to include in the functions list.\nAfter scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes.\n\n**Difference from scope_nodes:**\n- `scope_nodes` defines what nodes to query for functions\n- `nodes` filters which nodes appear in the output\n\n**Examples:**\n- `web-*` - Only show functions from web servers\n- Specific hostnames: `node1|node2|node3`\n" }, { "name": "options", "value": "debug", "type": "query", "description": "Comma-separated list of options to control response content and format.\n\n**Available Options:**\n- `minify` - Minimize JSON output (no pretty-printing)\n- `debug` - Include detailed function metadata and plugin information\n- `raw` - Include raw function definitions\n\n**Examples:**\n- `minify` - Compact JSON response\n- `debug,raw` - Full debug information\n" }, { "name": "timeout", "value": "10", "type": "query", "description": "Maximum time in seconds to wait for the query to complete before timing out.\n\n**Guidelines:**\n- Recommended: 10-30 seconds for most queries\n- Function listing is usually fast\n- Timeout mainly applies to very large infrastructures\n" }, { "name": "cardinality", "value": "500", "type": "query", "description": "Maximum number of nodes to include in the response to prevent overwhelming large responses.\nWhen this limit is exceeded, the response will indicate how many nodes were omitted.\n\n**Purpose:**\n- Prevent memory exhaustion from very large infrastructures\n- Control response size for performance\n- Useful when exploring large node sets incrementally\n\n**Recommendations:**\n- Small infrastructures (< 100 nodes): Use default\n- Medium infrastructures (100-1000 nodes): 500-1000\n- Large infrastructures (> 1000 nodes): Use filtering or increase limit carefully\n" } ] }, "docs": "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 inform" }, { "info": { "name": "OBSOLETE: Track async operation progress (use /api/v3/progress instead)", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v2/progress", "params": [ { "name": "transaction", "value": "", "type": "query", "description": "Transaction UUID from async operation" } ] }, "docs": "**⚠️ OBSOLETE API - Will be removed in future versions**\n\nThis endpoint is deprecated. Use `/api/v3/progress` instead, which provides the same functionality.\n\n**Migration:** Replace `/api/v2/progress` with `/api/v3/progress` in all API calls.\n\nTracks progress of long-running asynchronous operations using transaction UUID.\nUsed for polling function execution status and completion percentage.\n\n**Security & Access Control:**\n- 🔓 **Always Public API** - This endpoint is always accessible without au" }, { "info": { "name": "OBSOLETE: List available functions (use /api/v3/functions instead)", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v2/functions", "params": [ { "name": "scope_nodes", "value": "", "type": "query", "description": "A simple pattern limiting the nodes scope of the query. The scope controls both data and metadata response. The simple pattern is checked against the nodes' machine guid, node id and hostname. The default nodes scope is all nodes for which this Agent has data for. Usually the nodes scope is used to slice the entire dashboard (e.g. the Global Nodes Selector at the Netdata Cloud overview dashboard). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "nodes", "value": "", "type": "query", "description": "A simple pattern matching the nodes to be queried. This only controls the data response, not the metadata. The simple pattern is checked against the nodes' machine guid, node id, hostname. The default nodes selector is all the nodes matched by the nodes scope. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "options", "value": "", "type": "query", "description": "Options that affect data generation.\n* `jsonwrap` - Wrap the output in a JSON object with metadata about the query.\n* `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format.\n* `minify` - Remove unnecessary spaces and newlines from the output.\n* `debug` - Provide additional information in `jsonwrap` output to help tracing issues.\n* `nonzero` - Do not return dimensions that all their values are zero, to improve the visual appearance of charts. They will still be returned if all the dimensions are entirely zero.\n* `null2zero` - Replace `null` values with `0`.\n* `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off.\n* `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign.\n* `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest).\n* `min2max` - When flattening multi-dimensional data into a single metric format, use `max - min` instead of `sum`. This is EOL - use `/api/v2` to control aggregation across dimensions.\n* `percentage` - Convert all values into a percentage vs the row total. When enabled, Netdata will query all dimensions, even the ones that have not been selected or are hidden, to find the row total, in order to calculate the percentage of each dimension selected.\n* `seconds` - Output timestamps in seconds instead of dates.\n* `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates.\n* `unaligned` - by default queries are aligned to the the view, so that as time passes past data returned do not change. When a data query will not be used for visualization, `unaligned` can be given to avoid aligning the query time-frame for visual precision.\n* `match-ids`, `match-names`. By default filters match both IDs and names when they are available. Setting either of the two options will disable the other.\n* `anomaly-bit` - query the anomaly information instead of metric values. This is EOL, use `/api/v2` and `json2` format which always returns this information and many more.\n* `jw-anomaly-rates` - return anomaly rates as a separate result set in the same `json` format response. This is EOL, use `/api/v2` and `json2` format which always returns information and many more. \n* `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query.\n* `group-by-labels` - `/api/v2/data` returns in `jsonwrap` flattened labels per output dimension. These are used to identify the instances that have been aggregated into each dimension, making it possible to provide a map, like Netdata does for Kubernetes.\n* `natural-points` - return timestamps as found in the database. The result is again fixed-step, but the query engine attempts to align them with the timestamps found in the database.\n* `virtual-points` - return timestamps independent of the database alignment. This is needed aggregating data across multiple Netdata Agents, to ensure that their outputs do not need to be interpolated to be merged.\n* `selected-tier` - use data exclusively from the selected tier given with the `tier` parameter. This option is set automatically when the `tier` parameter is set.\n* `all-dimensions` - In `/api/v1` `jsonwrap` include metadata for all candidate metrics examined. In `/api/v2` this is standard behavior and no option is needed.\n* `label-quotes` - In `csv` output format, enclose each header label in quotes.\n* `objectrows` - Each row of value should be an object, not an array (only for `json` format).\n* `google_json` - Comply with google JSON/JSONP specs (only for `json` format).\n* `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth.\n* `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones.\n* `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration.\n* `rfc3339` - Return timestamps in RFC3339 format (e.g., \"2023-01-01T00:00:00Z\") instead of Unix timestamps.\n" }, { "name": "timeout", "value": "", "type": "query", "description": "Specify a timeout value in milliseconds after which the Agent will abort the query and return a 503 error. A value of 0 indicates no timeout.\n" }, { "name": "cardinality_limit", "value": "", "type": "query", "description": "Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit.\n" } ] }, "docs": "**⚠️ OBSOLETE API - Will be removed in future versions**\n\nThis endpoint is deprecated. Use `/api/v3/functions` instead, which provides the same functionality.\n\n**Migration:** Replace `/api/v2/functions` with `/api/v3/functions` in all API calls.\n\nLists all functions available on agents, including their descriptions, parameters, and capabilities.\nFunctions provide live operational data and diagnostic capabilities.\n\n**Security & Access Control:**\n- 📊 **Public Data API** - Bearer token optional, I" }, { "info": { "name": "function1", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v1/function", "params": [ { "name": "function", "value": "", "type": "query", "description": "The name of the function, as returned by the collector." }, { "name": "timeout", "value": "", "type": "query", "description": "Specify a timeout value in seconds after which the Agent will abort the query and return a 504 error. A value of 0 indicates no timeout, but some endpoints, like `weights`, do not accept infinite timeouts (they have a predefined default), so to disable the timeout it must be set to a really high value.\n" } ] }, "docs": "|\n\n**Security & Access Control:**\n- 📊 **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" }, { "info": { "name": "Get a list of all registered collector functions.", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v1/functions" }, "docs": "Collector functions are programs that can be executed on demand.\n\n**Security & Access Control:**\n- 📊 **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" } ] } ], "bundled": true }