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 nodes 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: nodes
description: Everything related to monitored nodes
paths:
/api/v2/nodes:
get:
deprecated: true
operationId: getNodes2
tags:
- nodes
summary: Nodes Info v2
description: 'Get a list of all nodes hosted by this Netdata Agent.
**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'
- $ref: '#/components/parameters/contextsQueryOptions'
responses:
'200':
description: OK
content:
application/json:
schema:
description: '`/api/v2/nodes` response for all nodes hosted by a Netdata Agent.
'
type: object
properties:
api:
$ref: '#/components/schemas/api'
agents:
$ref: '#/components/schemas/agents'
versions:
$ref: '#/components/schemas/versions'
nodes:
type: array
items:
$ref: '#/components/schemas/nodeFull'
/api/v3/nodes:
get:
operationId: getNodes3
tags:
- nodes
summary: Nodes Info v3
description: 'Get a list of all nodes hosted by this Netdata Agent.
**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'
- $ref: '#/components/parameters/contextsQueryOptions'
responses:
'200':
description: OK
content:
application/json:
schema:
description: '`/api/v3/nodes` response for all nodes hosted by a Netdata Agent.
'
type: object
properties:
api:
$ref: '#/components/schemas/api'
agents:
$ref: '#/components/schemas/agents'
versions:
$ref: '#/components/schemas/versions'
nodes:
type: array
items:
$ref: '#/components/schemas/nodeFull'
/api/v1/info:
get:
deprecated: true
operationId: getNodeInfo1
tags:
- nodes
summary: Node Info v1
description: "The info endpoint returns basic information about netdata. It provides:\n* netdata version\n* netdata unique id\n* list of hosts mirrored (includes itself)\n* Operating System, Virtualization, K8s nodes and Container technology information\n* List of active collector plugins and modules\n* Streaming information\n* number of alarms in the host\n * number of alarms in normal state\n * number of alarms in warning state\n * number of alarms in critical state\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: []
responses:
'200':
description: netdata basic information.
content:
application/json:
schema:
$ref: '#/components/schemas/info'
'503':
description: netdata daemon not ready (used for health checks).
/api/v3/info:
get:
operationId: info_v3
tags:
- nodes
summary: Retrieve detailed Netdata agent information across all nodes
description: 'Returns comprehensive information about Netdata agents running across the monitored infrastructure. This endpoint provides detailed metadata about each agent including version information, capabilities, collection status, and system configuration.
**What is Netdata Agent Information?**
The `info` endpoint provides detailed metadata about the Netdata monitoring agent itself, including:
- Agent version and build information
- System capabilities and features enabled
- Collection status and health
- Host configuration and labels
- Database information (storage, retention)
- Plugin and collector status
- Operating system details
- Hardware information
**Difference from /api/v3/nodes:**
- **`/api/v3/nodes`:** Returns lightweight node list with basic identification
- **`/api/v3/info`:** Returns comprehensive agent details with full capabilities and configuration
**Multi-Node Support:**
When queried on a Netdata Parent, this endpoint can return information for:
- The parent agent itself
- All child agents (streaming to the parent)
- Filtered subsets using scope_nodes/nodes parameters
**Use Cases:**
- **Infrastructure Inventory:** Complete catalog of all Netdata installations
- **Version Audits:** Find agents that need updates
- **Capability Discovery:** What features are available on each node
- **Health Monitoring:** Verify agent collection status
- **Configuration Management:** Understand how agents are configured
- **Troubleshooting:** Diagnose agent-specific issues
- **License/Compliance:** Track Netdata deployments
**Information Categories:**
**1. Agent Identity:**
- Unique agent ID (machine_guid)
- Hostname
- Agent version and commit
- Build information
**2. System Information:**
- Operating system and kernel
- CPU architecture
- Virtualization platform
- Container runtime (if applicable)
**3. Database & Storage:**
- Database mode (dbengine, ram, alloc)
- Retention period
- Storage capacity
- Disk space usage
**4. Features & Capabilities:**
- ML/anomaly detection status
- ACLK (cloud connection) status
- Streaming capabilities
- Available collectors
**5. Collection Status:**
- Number of charts collecting
- Number of dimensions
- Collection frequency
- Last collection timestamp
**6. Host Labels:**
- Custom labels assigned to the host
- Automatic labels (OS, architecture, etc.)
- Cloud provider information (if detected)
**Performance Characteristics:**
- Fast query (primarily metadata lookups)
- No time-series data processing
- Results can be cached for reasonable duration
- Supports filtering by node patterns
**Example Usage:**
```
# Get info for all nodes
GET /api/v3/info
# Get info for specific nodes
GET /api/v3/info?nodes=web-server-01,db-server-01
# Get info for nodes matching pattern
GET /api/v3/info?scope_nodes=prod-*
# Include specific options
GET /api/v3/info?options=full
```
**Response Format:**
Returns JSON with agent information grouped by node, including complete details about each agent''s capabilities, configuration, and current status.
**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: scope_nodes
in: query
description: 'Filter to specific nodes using simple pattern matching.
**Pattern Syntax:**
- `*` matches any characters
- Space-separated list for multiple patterns
- `!` prefix to exclude
- Combine with: `web* !web-test*`
**Examples:**
- `scope_nodes=web*` - All web servers
- `scope_nodes=prod-*` - All production nodes
- `scope_nodes=* !test*` - All except test nodes
**Use Cases:**
- Focus on specific infrastructure tiers
- Exclude development/test environments
- Group by naming conventions
When not specified, returns info for all nodes.
'
required: false
schema:
type: string
example: prod-*
- name: nodes
in: query
description: 'Filter to specific nodes by exact names.
Unlike `scope_nodes`, this requires exact node names (no patterns).
**Format:** Comma or pipe-separated list
**Examples:**
- `nodes=web-server-01` - Single node
- `nodes=web-server-01,db-server-01` - Multiple nodes
- `nodes=web-01|web-02` - Pipe separator
**Best Practice:**
- Use `nodes` when you know exact names
- Use `scope_nodes` for pattern-based filtering
When not specified, returns info for all nodes matching scope_nodes.
'
required: false
schema:
type: string
example: web-server-01,db-server-01
- name: options
in: query
description: 'Control the level of detail and what information to include in the response.
**Available Options:**
- `full` or `all` - Include all available information
- `labels` - Include host labels
- `uuids` - Include UUIDs and identifiers
- `deleted` - Include information about deleted/offline nodes
- `hidden` - Include hidden agents
**Examples:**
- `options=full` - Complete information
- `options=labels,uuids` - Labels and identifiers
- `options=labels|uuids` - Pipe separator also works
**Default Behavior:**
When not specified, returns standard information without deleted/hidden nodes and without excessive detail.
**Use Cases:**
- Inventory systems need `full` detail
- Label-based filtering needs `labels`
- Historical analysis may need `deleted`
'
required: false
schema:
type: string
example: full,labels
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- name: timeout
in: query
description: 'Maximum time in milliseconds to wait for the query to complete.
**Format:** Integer (milliseconds)
**Default:** Server default timeout
**Example:**
- `timeout=30000` - 30 second timeout
For agent info queries, timeouts are rarely needed as this is a fast metadata-only operation. However, on very large multi-node setups, you may want to limit query time.
'
required: false
schema:
type: integer
format: int64
minimum: 1000
example: 30000
- name: cardinality
in: query
description: 'Limit the number of nodes returned.
**Format:** Integer (maximum nodes)
**Default:** No limit
**Example:**
- `cardinality=100` - Return at most 100 nodes
**Use Cases:**
- Prevent huge responses in very large infrastructures
- Get a sample of nodes for testing
- Dashboard widgets with limited display space
When exceeded, response indicates how many nodes were omitted.
'
required: false
schema:
type: integer
minimum: 1
example: 100
responses:
'200':
description: "Success. Returns detailed Netdata agent information.\n\n**Response Structure:**\nThe response is a JSON object containing comprehensive agent information grouped by node.\n\n**Top-Level Structure:**\n- `agents`: Array of agent information objects, one per node\n\n**Per-Agent Information Includes:**\n\n**1. Identity:**\n- `machine_guid`: Unique agent identifier (UUID)\n- `hostname`: Node hostname\n- `agent_version`: Netdata version string\n- `agent_commit`: Git commit hash of build\n\n**2. System Information:**\n- `os_name`: Operating system name\n- `os_version`: OS version\n- `kernel_name`: Kernel name\n- `kernel_version`: Kernel version\n- `architecture`: CPU architecture (x86_64, aarch64, etc.)\n- `virtualization`: Virtualization platform (if any)\n- `container`: Container runtime (Docker, LXC, etc.)\n- `container_detection`: How container was detected\n\n**3. Database & Storage:**\n- `database_mode`: Storage mode (dbengine, ram, alloc, none)\n- `database_retention`: Data retention period in seconds\n- `database_size`: Current database size in bytes\n- `page_cache_size`: Page cache size\n- `metrics_stored`: Number of unique metrics\n\n**4. Features & Capabilities:**\n- `ml_enabled`: Machine learning / anomaly detection enabled\n- `ml_models_running`: Number of ML models active\n- `aclk_available`: Cloud connectivity available\n- `aclk_status`: Cloud connection status\n- `stream_compression`: Streaming compression supported\n- `web_enabled`: Web server enabled\n\n**5. Collection Status:**\n- `charts_count`: Number of charts being collected\n- `dimensions_count`: Number of dimensions (time-series)\n- `collectors_count`: Number of active collectors\n- `update_every`: Collection frequency in seconds\n- `history`: Retention in seconds\n- `memory_mode`: Memory storage mode\n\n**6. Host Labels:**\n- `host_labels`: Object containing all host labels\n - Includes automatic labels (_os_name, _architecture, etc.)\n - Includes custom labels assigned by user\n - May include cloud provider labels\n\n**7. Timestamps:**\n- `first_time_t`: Timestamp of oldest data point\n- `last_time_t`: Timestamp of newest data point\n- `now`: Current server time\n\n**8. Streaming Information (if applicable):**\n- `stream_status`: Streaming status (parent/child)\n- `stream_parents`: Parent nodes (if child)\n- `stream_children`: Child nodes (if parent)\n\n**Example Response Structure:**\n```json\n{\n \"agents\": [\n {\n \"machine_guid\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"hostname\": \"web-server-01\",\n \"agent_version\": \"v1.40.0\",\n \"os_name\": \"ubuntu\",\n \"os_version\": \"22.04\",\n \"kernel_version\": \"5.15.0\",\n \"architecture\": \"x86_64\",\n \"database_mode\": \"dbengine\",\n \"database_retention\": 86400,\n \"ml_enabled\": true,\n \"charts_count\": 425,\n \"dimensions_count\": 2850,\n \"update_every\": 1,\n \"host_labels\": {\n \"_os_name\": \"ubuntu\",\n \"_architecture\": \"x86_64\",\n \"environment\": \"production\",\n \"tier\": \"web\"\n }\n }\n ]\n}\n```\n\n**Response Characteristics:**\n- Content-Type: application/json\n- Can be cached (agent info changes infrequently)\n- Complete metadata without time-series data\n- Lightweight and fast to generate\n\n**Filtering:**\nResponse respects scope_nodes/nodes filters and cardinality limits.\n"
content:
application/json:
schema:
type: object
description: Comprehensive Netdata agent information
'400':
description: 'Bad request. Common causes:
- Invalid parameter values
- Malformed filter patterns
'
'500':
description: Internal server error during info retrieval.
/api/v3/node_instances:
get:
operationId: node_instances_v3
tags:
- nodes
summary: Retrieve chart instances organized by node across the infrastructure
description: "Returns information about all chart instances grouped by node. This endpoint provides a comprehensive view of what metrics are being collected on each node, organized by chart instances.\n\n**What are Node Instances?**\nNode instances represent the specific chart instances (individual monitoring targets) on each node:\n- Each node may have multiple instances of the same chart type\n- Examples: Multiple disks (sda, sdb, sdc), multiple network interfaces (eth0, eth1)\n- Instances represent the specific entities being monitored\n\n**Example:**\nFor disk monitoring:\n- Node: `web-server-01`\n - Instances: `disk.sda`, `disk.sdb`, `disk.nvme0n1`\n- Node: `db-server-01`\n - Instances: `disk.sda`, `disk.sdb`\n\n**Difference from Other Endpoints:**\n- **`/api/v3/nodes`:** Returns lightweight node list\n- **`/api/v3/info`:** Returns detailed agent information\n- **`/api/v3/node_instances`:** Returns what chart instances each node has (what's being monitored)\n- **`/api/v3/contexts`:** Returns contexts aggregated across all nodes\n\n**Use Cases:**\n- **Infrastructure Discovery:** What devices/services are monitored on each node\n- **Capacity Planning:** Understand monitoring coverage per node\n- **Configuration Verification:** Verify expected charts are collecting\n- **Collector Status:** See which collectors are active per node\n- **Instance Inventory:** Complete catalog of monitored entities\n- **Troubleshooting:** Find which nodes monitor specific instances\n\n**Response Organization:**\nResults are organized hierarchically:\n1. **By Node:** Top-level grouping by node hostname\n2. **By Context:** Charts grouped by their context (e.g., disk.space)\n3. **By Instance:** Individual chart instances within each context\n\n**Performance Characteristics:**\n- Medium query cost (metadata aggregation across nodes)\n- Response size grows with number of nodes and instances\n- Can be filtered to reduce response size\n- Results can be cached (instances change infrequently)\n\n**Example Query Patterns:**\n```\n# Get all instances across all nodes\nGET /api/v3/node_instances\n\n# Get instances for specific nodes\nGET /api/v3/node_instances?nodes=web-server-01,db-server-01\n\n# Get instances for nodes matching pattern\nGET /api/v3/node_instances?scope_nodes=prod-*\n\n# Limit response size\nGET /api/v3/node_instances?cardinality=100\n```\n\n**Response Includes:**\n- Node identification (hostname, machine_guid)\n- Agent information (version, capabilities)\n- All chart instances organized by context\n- Instance-specific metadata (labels, units, dimensions)\n- Instance collection status\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
description: 'Filter to specific nodes using pattern matching.
**Pattern Syntax:**
- `*` matches any characters
- Space-separated for multiple patterns
- `!` prefix excludes
- Example: `prod-* !prod-test*`
**Examples:**
- `scope_nodes=web*` - All web servers
- `scope_nodes=db-* cache-*` - Database and cache nodes
- `scope_nodes=* !test*` - All except test nodes
When not specified, returns instances from all nodes.
'
required: false
schema:
type: string
example: prod-*
- name: nodes
in: query
description: 'Filter to specific nodes by exact names.
**Format:** Comma or pipe-separated exact names
**Examples:**
- `nodes=web-server-01` - Single node
- `nodes=web-01,db-01` - Multiple nodes
**Best Practice:** Use `nodes` for exact names, `scope_nodes` for patterns.
When not specified, returns instances from all nodes.
'
required: false
schema:
type: string
example: web-server-01,db-server-01
- name: options
in: query
description: 'Control response detail level and included information.
**Available Options:**
- `full` or `all` - Complete instance information
- `labels` - Include instance labels
- `uuids` - Include UUIDs and identifiers
- `deleted` - Include deleted/offline instances
- `hidden` - Include hidden instances
- `instances` or `charts` - Include chart instances (default)
- `metrics` or `dimensions` - Include dimension details
**Examples:**
- `options=full` - All information
- `options=labels,dimensions` - Labels and dimension details
- `options=labels|uuids` - Pipe separator
**Default:** Returns basic instance information without excessive detail.
'
required: false
schema:
type: string
example: full,labels,dimensions
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- name: timeout
in: query
description: 'Maximum time in milliseconds to wait for query completion.
**Format:** Integer (milliseconds)
**Default:** Server default timeout
**Example:** `timeout=30000` (30 seconds)
For large multi-node infrastructures, you may need to increase timeout to allow complete instance enumeration.
'
required: false
schema:
type: integer
format: int64
minimum: 1000
example: 30000
- name: cardinality
in: query
description: 'Limit the number of instances returned per node.
**Format:** Integer (max instances per node)
**Default:** No limit
**Example:** `cardinality=500` - At most 500 instances per node
**Use Cases:**
- Prevent huge responses from nodes with many instances
- Sample instances for testing
- Dashboard widgets with limited space
When exceeded, response indicates how many instances were omitted per node.
'
required: false
schema:
type: integer
minimum: 1
example: 500
responses:
'200':
description: "Success. Returns chart instances organized by node.\n\n**Response Structure:**\n```json\n{\n \"nodes\": [\n {\n \"machine_guid\": \"uuid\",\n \"hostname\": \"web-server-01\",\n \"agent_version\": \"v1.40.0\",\n \"contexts\": [\n {\n \"context\": \"disk.space\",\n \"instances\": [\n {\n \"id\": \"disk.sda\",\n \"name\": \"disk sda\",\n \"family\": \"sda\",\n \"labels\": {...},\n \"dimensions\": [...],\n \"status\": \"active\"\n },\n {\n \"id\": \"disk.sdb\",\n \"name\": \"disk sdb\",\n \"family\": \"sdb\",\n \"labels\": {...},\n \"dimensions\": [...],\n \"status\": \"active\"\n }\n ]\n },\n {\n \"context\": \"net.net\",\n \"instances\": [\n {\n \"id\": \"net.eth0\",\n \"name\": \"eth0\",\n \"family\": \"eth0\",\n \"labels\": {...},\n \"dimensions\": [...],\n \"status\": \"active\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n**Response Fields:**\n\n**Node Level:**\n- `machine_guid`: Unique node identifier\n- `hostname`: Node hostname\n- `agent_version`: Netdata version on this node\n- `contexts`: Array of contexts with their instances\n\n**Context Level:**\n- `context`: Context name (e.g., \"disk.space\", \"system.cpu\")\n- `instances`: Array of chart instances for this context\n\n**Instance Level:**\n- `id`: Chart instance ID (e.g., \"disk.sda\")\n- `name`: Human-readable instance name\n- `family`: Chart family/grouping\n- `labels`: Instance-specific labels\n- `dimensions`: Array of dimensions (metrics) collected\n- `status`: Collection status (active, stale, offline)\n- `units`: Unit of measurement\n- `chart_type`: Chart visualization type\n- `priority`: Display priority\n\n**Dimension Information (when options=dimensions):**\n- `id`: Dimension identifier\n- `name`: Dimension display name\n- `algorithm`: Aggregation algorithm\n- `multiplier`, `divisor`: Value transformation\n\n**Label Information (when options=labels):**\n- Instance labels provide additional metadata\n- Examples: disk_type=ssd, interface_speed=1000, mount_point=/\n\n**Response Characteristics:**\n- Content-Type: application/json\n- Cacheable (instances change infrequently)\n- Size grows with number of nodes and instances\n- Organized hierarchically for easy navigation\n\n**Filtering:**\nResponse respects scope_nodes/nodes filters and cardinality limits.\n"
content:
application/json:
schema:
type: object
description: Chart instances organized by node
'400':
description: 'Bad request. Common causes:
- Invalid parameter values
- Malformed filter patterns
'
'500':
description: Internal server error during instance enumeration.
/api/v3/stream_path:
get:
operationId: stream_path
tags:
- nodes
summary: Retrieve streaming topology path for nodes
description: "**V3 SPECIFIC ENDPOINT**\n\nReturns the streaming path and topology showing how nodes are connected in the Netdata infrastructure.\nThis endpoint reveals the parent-child relationships between nodes, showing which nodes stream data\nto which parents, creating a hierarchical view of the monitoring infrastructure.\n\n**Streaming Topology:**\n- **Parent nodes**: Nodes that receive streaming data from child nodes\n- **Child nodes**: Nodes that send their metrics to parent nodes for centralization\n- **Streaming path**: The complete chain from child → parent → grandparent (if any)\n\n**Use Cases:**\n- Understand infrastructure hierarchy and data flow\n- Identify parent nodes that aggregate data from multiple children\n- Debug streaming connectivity issues\n- Plan infrastructure changes and reorganization\n- Visualize the complete monitoring topology\n\n**Common Usage Patterns:**\n\n1. **Get complete streaming topology:**\n ```\n /api/v3/stream_path\n ```\n\n2. **Filter by specific nodes:**\n ```\n /api/v3/stream_path?nodes=child-node-1|child-node-2\n ```\n\n3. **Scope to nodes matching pattern:**\n ```\n /api/v3/stream_path?scope_nodes=prod-*\n ```\n\n**Response Structure:**\nThe response includes nodes organized by their streaming relationships, showing:\n- Node hostnames and machine GUIDs\n- Parent-child relationships\n- Streaming connection status (live/stale/offline)\n- Complete path from each child to root parent\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 topology analysis.
**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 streaming path response.
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 analyze for relationships
- `nodes` filters which nodes to include in the output
**Examples:**
- `web-*` - Only show web server nodes in output
- `parent-*` - Only show parent nodes
- Specific hostnames
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netdata/refs/heads/main/openapi/netdata-nodes-api-openapi.yml