| 1 | # yaml-language-server: $schema=https://spec.openapis.org/oas/3.0/schema/2024-10-18 |
| 2 | openapi: 3.0.0 |
| 3 | info: |
| 4 | title: Netdata API |
| 5 | description: | |
| 6 | Real-time performance and health monitoring. |
| 7 | |
| 8 | ## API Versions |
| 9 | |
| 10 | Netdata provides three API versions: |
| 11 | - **v1**: The original API, focused on single-node operations |
| 12 | - **v2**: Multi-node API with advanced grouping and aggregation capabilities |
| 13 | - **v3**: The latest API version that combines v1 and v2 endpoints and may include additional features |
| 14 | |
| 15 | ### v3 API Endpoints |
| 16 | |
| 17 | The v3 API provides the current, actively maintained endpoints: |
| 18 | - `/api/v3/data` - Multi-dimensional data queries |
| 19 | - `/api/v3/weights` - Metric scoring/correlation |
| 20 | - `/api/v3/contexts` - Context metadata |
| 21 | - `/api/v3/nodes` - Node information |
| 22 | - `/api/v3/q` - Full-text search |
| 23 | - `/api/v3/alerts` - Alert information |
| 24 | - `/api/v3/alert_transitions` - Alert state transitions |
| 25 | - `/api/v3/alert_config` - Alert configuration |
| 26 | - `/api/v3/functions` - Available functions |
| 27 | - `/api/v3/function` - Execute functions |
| 28 | - `/api/v3/info` - Agent information |
| 29 | - `/api/v3/node_instances` - Node instance information |
| 30 | - `/api/v3/stream_path` - Streaming topology |
| 31 | - `/api/v3/versions` - Version information |
| 32 | - `/api/v3/badge.svg` - Dynamic badges |
| 33 | - `/api/v3/allmetrics` - Export metrics |
| 34 | - `/api/v3/context` - Single context info |
| 35 | - `/api/v3/variable` - Variable information |
| 36 | - `/api/v3/config` - Dynamic configuration |
| 37 | - `/api/v3/settings` - Agent settings |
| 38 | - `/api/v3/me` - Current user information |
| 39 | - `/api/v3/claim` - Agent claiming |
| 40 | - Additional management and streaming endpoints |
| 41 | |
| 42 | **Note:** V1 and V2 APIs are deprecated and maintained for backwards compatibility only. New integrations should use V3 exclusively. |
| 43 | version: "v1-rolling" |
| 44 | contact: |
| 45 | name: Netdata Agent API |
| 46 | email: info@netdata.cloud |
| 47 | url: https://netdata.cloud |
| 48 | license: |
| 49 | name: GPL v3+ |
| 50 | url: https://github.com/netdata/netdata/blob/master/LICENSE |
| 51 | servers: |
| 52 | - url: https://registry.my-netdata.io |
| 53 | - url: http://registry.my-netdata.io |
| 54 | - url: http://localhost:19999 |
| 55 | tags: |
| 56 | - name: nodes |
| 57 | description: Everything related to monitored nodes |
| 58 | - name: charts |
| 59 | description: Everything related to chart instances - DO NOT USE IN NEW CODE - use contexts instead |
| 60 | - name: contexts |
| 61 | description: Everything related contexts - in new code, use this instead of charts |
| 62 | - name: data |
| 63 | description: Everything related to data queries |
| 64 | - name: badges |
| 65 | description: Everything related to dynamic badges based on metric data |
| 66 | - name: weights |
| 67 | description: Everything related to scoring / weighting metrics |
| 68 | - name: functions |
| 69 | description: Everything related to functions |
| 70 | - name: alerts |
| 71 | description: Everything related to alerts |
| 72 | - name: management |
| 73 | description: Everything related to managing netdata Agents |
| 74 | paths: |
| 75 | /api/v2/nodes: |
| 76 | get: |
| 77 | deprecated: true |
| 78 | operationId: getNodes2 |
| 79 | tags: |
| 80 | - nodes |
| 81 | summary: Nodes Info v2 |
| 82 | description: | |
| 83 | Get a list of all nodes hosted by this Netdata Agent. |
| 84 | |
| 85 | **Security & Access Control:** |
| 86 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 87 | - **Default Access:** Public (no authentication required) |
| 88 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 89 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 90 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 91 | security: |
| 92 | - {} |
| 93 | - bearerAuth: [] |
| 94 | parameters: |
| 95 | - $ref: '#/components/parameters/scopeNodes' |
| 96 | - $ref: '#/components/parameters/scopeContexts' |
| 97 | - $ref: '#/components/parameters/filterNodes' |
| 98 | - $ref: '#/components/parameters/filterContexts' |
| 99 | - $ref: '#/components/parameters/contextsQueryOptions' |
| 100 | responses: |
| 101 | "200": |
| 102 | description: OK |
| 103 | content: |
| 104 | application/json: |
| 105 | schema: |
| 106 | description: | |
| 107 | `/api/v2/nodes` response for all nodes hosted by a Netdata Agent. |
| 108 | type: object |
| 109 | properties: |
| 110 | api: |
| 111 | $ref: '#/components/schemas/api' |
| 112 | agents: |
| 113 | $ref: '#/components/schemas/agents' |
| 114 | versions: |
| 115 | $ref: '#/components/schemas/versions' |
| 116 | nodes: |
| 117 | type: array |
| 118 | items: |
| 119 | $ref: '#/components/schemas/nodeFull' |
| 120 | /api/v3/nodes: |
| 121 | get: |
| 122 | operationId: getNodes3 |
| 123 | tags: |
| 124 | - nodes |
| 125 | summary: Nodes Info v3 |
| 126 | description: | |
| 127 | Get a list of all nodes hosted by this Netdata Agent. |
| 128 | |
| 129 | **Security & Access Control:** |
| 130 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 131 | - **Default Access:** Public (no authentication required) |
| 132 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 133 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 134 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 135 | security: |
| 136 | - {} |
| 137 | - bearerAuth: [] |
| 138 | parameters: |
| 139 | - $ref: '#/components/parameters/scopeNodes' |
| 140 | - $ref: '#/components/parameters/scopeContexts' |
| 141 | - $ref: '#/components/parameters/filterNodes' |
| 142 | - $ref: '#/components/parameters/filterContexts' |
| 143 | - $ref: '#/components/parameters/contextsQueryOptions' |
| 144 | responses: |
| 145 | "200": |
| 146 | description: OK |
| 147 | content: |
| 148 | application/json: |
| 149 | schema: |
| 150 | description: | |
| 151 | `/api/v3/nodes` response for all nodes hosted by a Netdata Agent. |
| 152 | type: object |
| 153 | properties: |
| 154 | api: |
| 155 | $ref: '#/components/schemas/api' |
| 156 | agents: |
| 157 | $ref: '#/components/schemas/agents' |
| 158 | versions: |
| 159 | $ref: '#/components/schemas/versions' |
| 160 | nodes: |
| 161 | type: array |
| 162 | items: |
| 163 | $ref: '#/components/schemas/nodeFull' |
| 164 | /api/v2/contexts: |
| 165 | get: |
| 166 | deprecated: true |
| 167 | operationId: getContexts2 |
| 168 | tags: |
| 169 | - contexts |
| 170 | summary: Contexts Info v2 |
| 171 | description: | |
| 172 | Get a list of all contexts, across all nodes, hosted by this Netdata Agent. |
| 173 | |
| 174 | **Security & Access Control:** |
| 175 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 176 | - **Default Access:** Public (no authentication required) |
| 177 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 178 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 179 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 180 | security: |
| 181 | - {} |
| 182 | - bearerAuth: [] |
| 183 | parameters: |
| 184 | - $ref: '#/components/parameters/scopeNodes' |
| 185 | - $ref: '#/components/parameters/scopeContexts' |
| 186 | - $ref: '#/components/parameters/filterNodes' |
| 187 | - $ref: '#/components/parameters/filterContexts' |
| 188 | - $ref: '#/components/parameters/contextsQueryOptions' |
| 189 | responses: |
| 190 | "200": |
| 191 | description: OK |
| 192 | content: |
| 193 | application/json: |
| 194 | schema: |
| 195 | $ref: '#/components/schemas/contexts2' |
| 196 | /api/v3/contexts: |
| 197 | get: |
| 198 | operationId: getContexts3 |
| 199 | tags: |
| 200 | - contexts |
| 201 | summary: Contexts Info v3 |
| 202 | description: | |
| 203 | Get a list of all contexts, across all nodes, hosted by this Netdata Agent. |
| 204 | |
| 205 | **Security & Access Control:** |
| 206 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 207 | - **Default Access:** Public (no authentication required) |
| 208 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 209 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 210 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 211 | security: |
| 212 | - {} |
| 213 | - bearerAuth: [] |
| 214 | parameters: |
| 215 | - $ref: '#/components/parameters/scopeNodes' |
| 216 | - $ref: '#/components/parameters/scopeContexts' |
| 217 | - $ref: '#/components/parameters/filterNodes' |
| 218 | - $ref: '#/components/parameters/filterContexts' |
| 219 | - $ref: '#/components/parameters/contextsQueryOptions' |
| 220 | responses: |
| 221 | "200": |
| 222 | description: OK |
| 223 | content: |
| 224 | application/json: |
| 225 | schema: |
| 226 | $ref: '#/components/schemas/contexts2' |
| 227 | /api/v2/q: |
| 228 | get: |
| 229 | deprecated: true |
| 230 | operationId: q2 |
| 231 | tags: |
| 232 | - contexts |
| 233 | summary: Full Text Search v2 |
| 234 | description: | |
| 235 | Get a list of contexts, across all nodes, hosted by this Netdata Agent, matching a string expression |
| 236 | |
| 237 | **Security & Access Control:** |
| 238 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 239 | - **Default Access:** Public (no authentication required) |
| 240 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 241 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 242 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 243 | security: |
| 244 | - {} |
| 245 | - bearerAuth: [] |
| 246 | parameters: |
| 247 | - name: q |
| 248 | in: query |
| 249 | description: The strings to search for, formatted as a simple pattern |
| 250 | required: true |
| 251 | schema: |
| 252 | type: string |
| 253 | format: simple pattern |
| 254 | - $ref: '#/components/parameters/scopeNodes' |
| 255 | - $ref: '#/components/parameters/scopeContexts' |
| 256 | - $ref: '#/components/parameters/filterNodes' |
| 257 | - $ref: '#/components/parameters/filterContexts' |
| 258 | - $ref: '#/components/parameters/contextsQueryOptions' |
| 259 | responses: |
| 260 | "200": |
| 261 | description: OK |
| 262 | content: |
| 263 | application/json: |
| 264 | schema: |
| 265 | $ref: '#/components/schemas/contexts2' |
| 266 | /api/v3/q: |
| 267 | get: |
| 268 | operationId: q3 |
| 269 | tags: |
| 270 | - contexts |
| 271 | summary: Full Text Search v3 |
| 272 | description: | |
| 273 | Get a list of contexts, across all nodes, hosted by this Netdata Agent, matching a string expression. |
| 274 | |
| 275 | **Security & Access Control:** |
| 276 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 277 | - **Default Access:** Public (no authentication required) |
| 278 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 279 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 280 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 281 | security: |
| 282 | - {} |
| 283 | - bearerAuth: [] |
| 284 | parameters: |
| 285 | - name: q |
| 286 | in: query |
| 287 | description: The strings to search for, formatted as a simple pattern |
| 288 | required: true |
| 289 | schema: |
| 290 | type: string |
| 291 | format: simple pattern |
| 292 | - $ref: '#/components/parameters/scopeNodes' |
| 293 | - $ref: '#/components/parameters/scopeContexts' |
| 294 | - $ref: '#/components/parameters/filterNodes' |
| 295 | - $ref: '#/components/parameters/filterContexts' |
| 296 | - $ref: '#/components/parameters/contextsQueryOptions' |
| 297 | responses: |
| 298 | "200": |
| 299 | description: OK |
| 300 | content: |
| 301 | application/json: |
| 302 | schema: |
| 303 | $ref: '#/components/schemas/contexts2' |
| 304 | /api/v1/info: |
| 305 | get: |
| 306 | deprecated: true |
| 307 | operationId: getNodeInfo1 |
| 308 | tags: |
| 309 | - nodes |
| 310 | summary: Node Info v1 |
| 311 | description: | |
| 312 | The info endpoint returns basic information about netdata. It provides: |
| 313 | * netdata version |
| 314 | * netdata unique id |
| 315 | * list of hosts mirrored (includes itself) |
| 316 | * Operating System, Virtualization, K8s nodes and Container technology information |
| 317 | * List of active collector plugins and modules |
| 318 | * Streaming information |
| 319 | * number of alarms in the host |
| 320 | * number of alarms in normal state |
| 321 | * number of alarms in warning state |
| 322 | * number of alarms in critical state |
| 323 | |
| 324 | **Security & Access Control:** |
| 325 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 326 | - **Default Access:** Public (no authentication required) |
| 327 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 328 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 329 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 330 | security: |
| 331 | - {} |
| 332 | - bearerAuth: [] |
| 333 | responses: |
| 334 | "200": |
| 335 | description: netdata basic information. |
| 336 | content: |
| 337 | application/json: |
| 338 | schema: |
| 339 | $ref: "#/components/schemas/info" |
| 340 | "503": |
| 341 | description: netdata daemon not ready (used for health checks). |
| 342 | /api/v1/charts: |
| 343 | get: |
| 344 | deprecated: true |
| 345 | operationId: getNodeCharts1 |
| 346 | tags: |
| 347 | - charts |
| 348 | summary: List all charts v1 - EOL |
| 349 | description: The charts endpoint returns a summary about all charts stored in the |
| 350 | netdata server. |
| 351 | |
| 352 | **Security & Access Control:** |
| 353 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 354 | - **Default Access:** Public (no authentication required) |
| 355 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 356 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 357 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 358 | security: |
| 359 | - {} |
| 360 | - bearerAuth: [] |
| 361 | responses: |
| 362 | "200": |
| 363 | description: An array of charts. |
| 364 | content: |
| 365 | application/json: |
| 366 | schema: |
| 367 | $ref: "#/components/schemas/chart_summary" |
| 368 | /api/v1/chart: |
| 369 | get: |
| 370 | deprecated: true |
| 371 | operationId: getNodeChart1 |
| 372 | tags: |
| 373 | - charts |
| 374 | summary: Get one chart v1 - EOL |
| 375 | description: The chart endpoint returns detailed information about a chart. |
| 376 | |
| 377 | **Security & Access Control:** |
| 378 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 379 | - **Default Access:** Public (no authentication required) |
| 380 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 381 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 382 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 383 | security: |
| 384 | - {} |
| 385 | - bearerAuth: [] |
| 386 | parameters: |
| 387 | - $ref: '#/components/parameters/chart' |
| 388 | responses: |
| 389 | "200": |
| 390 | description: A javascript object with detailed information about the chart. |
| 391 | content: |
| 392 | application/json: |
| 393 | schema: |
| 394 | $ref: "#/components/schemas/chart" |
| 395 | "400": |
| 396 | description: No chart id was supplied in the request. |
| 397 | "404": |
| 398 | description: No chart with the given id is found. |
| 399 | /api/v1/contexts: |
| 400 | get: |
| 401 | deprecated: true |
| 402 | operationId: getNodeContexts1 |
| 403 | tags: |
| 404 | - contexts |
| 405 | summary: Get a list of all node contexts available v1 |
| 406 | description: The contexts endpoint returns a summary about all contexts stored in the |
| 407 | netdata server. |
| 408 | |
| 409 | **Security & Access Control:** |
| 410 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 411 | - **Default Access:** Public (no authentication required) |
| 412 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 413 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 414 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 415 | security: |
| 416 | - {} |
| 417 | - bearerAuth: [] |
| 418 | parameters: |
| 419 | - $ref: '#/components/parameters/dimensions' |
| 420 | - $ref: '#/components/parameters/chart_label_key' |
| 421 | - $ref: '#/components/parameters/chart_labels_filter' |
| 422 | - $ref: '#/components/parameters/contextOptions1' |
| 423 | - $ref: '#/components/parameters/after' |
| 424 | - $ref: '#/components/parameters/before' |
| 425 | responses: |
| 426 | "200": |
| 427 | description: An array of contexts. |
| 428 | content: |
| 429 | application/json: |
| 430 | schema: |
| 431 | $ref: "#/components/schemas/context_summary" |
| 432 | /api/v1/context: |
| 433 | get: |
| 434 | deprecated: true |
| 435 | operationId: getNodeContext1 |
| 436 | tags: |
| 437 | - contexts |
| 438 | summary: Get info about a specific context |
| 439 | description: | |
| 440 | The context endpoint returns detailed information about a given context. |
| 441 | The `context` parameter is required for this call. |
| 442 | |
| 443 | **Security & Access Control:** |
| 444 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 445 | - **Default Access:** Public (no authentication required) |
| 446 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 447 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 448 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 449 | security: |
| 450 | - {} |
| 451 | - bearerAuth: [] |
| 452 | parameters: |
| 453 | - $ref: '#/components/parameters/context' |
| 454 | - $ref: '#/components/parameters/dimensions' |
| 455 | - $ref: '#/components/parameters/chart_label_key' |
| 456 | - $ref: '#/components/parameters/chart_labels_filter' |
| 457 | - $ref: '#/components/parameters/contextOptions1' |
| 458 | - $ref: '#/components/parameters/after' |
| 459 | - $ref: '#/components/parameters/before' |
| 460 | responses: |
| 461 | "200": |
| 462 | description: A javascript object with detailed information about the context. |
| 463 | content: |
| 464 | application/json: |
| 465 | schema: |
| 466 | $ref: "#/components/schemas/context" |
| 467 | "400": |
| 468 | description: No context id was supplied in the request. |
| 469 | "404": |
| 470 | description: No context with the given id is found. |
| 471 | /api/v3/context: |
| 472 | get: |
| 473 | operationId: getNodeContext3 |
| 474 | tags: |
| 475 | - contexts |
| 476 | summary: Get info about a specific context - Latest API |
| 477 | description: | |
| 478 | The context endpoint returns detailed information about a specific monitoring context across all nodes. |
| 479 | |
| 480 | This is the latest version (v3) of the context API. It provides the same functionality as v1 but may include additional features in the future. |
| 481 | |
| 482 | **What is a Context?** |
| 483 | A context is a grouping of charts that monitor the same type of metric across different instances. For example: |
| 484 | - `system.cpu` - CPU usage (one chart per node) |
| 485 | - `disk.io` - Disk I/O operations (one chart per disk) |
| 486 | - `net.packets` - Network packets (one chart per network interface) |
| 487 | |
| 488 | **Use Cases:** |
| 489 | - Get metadata about a specific metric type across all instances and nodes |
| 490 | - Discover which charts belong to a context |
| 491 | - Filter charts by labels or dimensions |
| 492 | - Understand metric families, units, and chart types |
| 493 | - Build dynamic dashboards that adapt to available instances |
| 494 | |
| 495 | The response includes all charts that belong to the specified context, with their metadata, dimensions, labels, and current availability status. |
| 496 | |
| 497 | **Security & Access Control:** |
| 498 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 499 | - **Default Access:** Public (no authentication required) |
| 500 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 501 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 502 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 503 | security: |
| 504 | - {} |
| 505 | - bearerAuth: [] |
| 506 | parameters: |
| 507 | - name: context |
| 508 | in: query |
| 509 | description: | |
| 510 | The context identifier to query. This is a required parameter. |
| 511 | |
| 512 | A context represents a type of metric collected across multiple instances. Each context groups charts that measure the same thing but for different entities. |
| 513 | |
| 514 | **Common Context Examples:** |
| 515 | - `system.cpu` - CPU utilization metrics |
| 516 | - `system.ram` - RAM usage metrics |
| 517 | - `disk.io` - Disk I/O operations |
| 518 | - `disk.ops` - Disk operation counts |
| 519 | - `net.packets` - Network packet statistics |
| 520 | - `net.drops` - Network packet drops |
| 521 | - `cgroup.cpu` - Container CPU usage |
| 522 | - `nginx.requests` - Nginx request rates |
| 523 | |
| 524 | **Finding Available Contexts:** |
| 525 | Use the `/api/v3/contexts` endpoint to get a list of all available contexts. |
| 526 | |
| 527 | **Alias:** Can also be specified as `ctx` for brevity. |
| 528 | required: true |
| 529 | schema: |
| 530 | type: string |
| 531 | example: "system.cpu" |
| 532 | - $ref: '#/components/parameters/dimensions' |
| 533 | - $ref: '#/components/parameters/chart_label_key' |
| 534 | - $ref: '#/components/parameters/chart_labels_filter' |
| 535 | - name: options |
| 536 | in: query |
| 537 | description: | |
| 538 | Comma or pipe-separated list of options to control the response content and format. |
| 539 | |
| 540 | **Available Options:** |
| 541 | - `full` or `all` - Include all possible information (equivalent to enabling all options below) |
| 542 | - `charts` - Include the list of charts belonging to this context |
| 543 | - `dimensions` - Include dimension information for each chart |
| 544 | - `queue` - Include data collection queue statistics |
| 545 | - `flags` - Include internal flags and states |
| 546 | - `labels` - Include chart labels |
| 547 | - `alerts` - Include alert configurations and states for this context |
| 548 | |
| 549 | **Option Combinations:** |
| 550 | Options can be combined. For example: `options=charts,dimensions,labels` will include charts with their dimensions and labels. |
| 551 | |
| 552 | **Default Behavior:** |
| 553 | When not specified, returns basic context information without detailed chart data. |
| 554 | |
| 555 | **Examples:** |
| 556 | - `options=full` - Complete information |
| 557 | - `options=charts,dimensions` - Charts with dimension details |
| 558 | - `options=charts|labels` - Charts with labels (pipe separator) |
| 559 | required: false |
| 560 | schema: |
| 561 | type: string |
| 562 | examples: |
| 563 | minimal: |
| 564 | value: "" |
| 565 | summary: Basic context info only |
| 566 | standard: |
| 567 | value: "charts,dimensions" |
| 568 | summary: Charts with dimensions |
| 569 | complete: |
| 570 | value: "full" |
| 571 | summary: All available information |
| 572 | - name: after |
| 573 | in: query |
| 574 | description: | |
| 575 | Return only charts that have collected data after this timestamp. |
| 576 | |
| 577 | This filters charts based on their data collection activity, excluding charts that haven't collected data since the specified time. |
| 578 | |
| 579 | **Format:** Unix timestamp in seconds |
| 580 | |
| 581 | **Use Cases:** |
| 582 | - Find recently active charts |
| 583 | - Exclude stale or obsolete charts |
| 584 | - Filter charts by collection timeframe |
| 585 | |
| 586 | **Example:** `after=1609459200` (charts active after January 1, 2021) |
| 587 | |
| 588 | When not specified, all charts are included regardless of their last update time. |
| 589 | required: false |
| 590 | schema: |
| 591 | type: integer |
| 592 | format: int64 |
| 593 | example: 1609459200 |
| 594 | - name: before |
| 595 | in: query |
| 596 | description: | |
| 597 | Return only charts that have collected data before this timestamp. |
| 598 | |
| 599 | This filters charts based on their data collection activity, excluding charts that only have data after the specified time. |
| 600 | |
| 601 | **Format:** Unix timestamp in seconds |
| 602 | |
| 603 | **Use Cases:** |
| 604 | - Historical analysis of chart availability |
| 605 | - Find charts that were active during a specific time period |
| 606 | - Exclude newer charts from results |
| 607 | |
| 608 | **Example:** `before=1640995200` (charts active before January 1, 2022) |
| 609 | |
| 610 | When combined with `after`, you can specify an exact time window: |
| 611 | `after=1609459200&before=1640995200` (charts active during 2021) |
| 612 | |
| 613 | When not specified, all charts are included regardless of their collection timeline. |
| 614 | required: false |
| 615 | schema: |
| 616 | type: integer |
| 617 | format: int64 |
| 618 | example: 1640995200 |
| 619 | responses: |
| 620 | "200": |
| 621 | description: | |
| 622 | Success. Returns detailed information about the requested context. |
| 623 | |
| 624 | The response is a JSON object containing: |
| 625 | - Context metadata (name, title, family, units, chart type) |
| 626 | - List of charts belonging to this context (when options=charts) |
| 627 | - Dimension information (when options=dimensions) |
| 628 | - Chart labels (when options=labels) |
| 629 | - Alert configurations (when options=alerts) |
| 630 | - Collection statistics (when options=queue) |
| 631 | |
| 632 | **Response Structure:** |
| 633 | The exact structure depends on the options parameter. With `options=full`, you get complete information including all charts, their dimensions, labels, and current states. |
| 634 | content: |
| 635 | application/json: |
| 636 | schema: |
| 637 | $ref: "#/components/schemas/context" |
| 638 | "400": |
| 639 | description: | |
| 640 | Bad request. Common causes: |
| 641 | - Missing required 'context' parameter |
| 642 | - Invalid parameter values |
| 643 | - Malformed filter patterns |
| 644 | "404": |
| 645 | description: | |
| 646 | Not found. The specified context does not exist on this Netdata agent. |
| 647 | |
| 648 | This can occur when: |
| 649 | - The context name is misspelled |
| 650 | - The context is not being collected on this agent |
| 651 | - The context was available but is now obsolete |
| 652 | "500": |
| 653 | description: Internal server error. Usually indicates the server is out of memory. |
| 654 | /api/v1/config: |
| 655 | get: |
| 656 | deprecated: true |
| 657 | operationId: getConfig |
| 658 | tags: |
| 659 | - dyncfg |
| 660 | description: | |
| 661 | Get dynamic configuration information. |
| 662 | |
| 663 | **Security & Access Control:** |
| 664 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 665 | - **Default Access:** Public (no authentication required) |
| 666 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 667 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 668 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 669 | security: |
| 670 | - {} |
| 671 | - bearerAuth: [] |
| 672 | parameters: |
| 673 | - name: action |
| 674 | in: query |
| 675 | description: The type of information required |
| 676 | schema: |
| 677 | type: string |
| 678 | enum: |
| 679 | - tree |
| 680 | - schema |
| 681 | - get |
| 682 | - enable |
| 683 | - disable |
| 684 | - restart |
| 685 | default: tree |
| 686 | - name: id |
| 687 | in: query |
| 688 | description: The ID of the dynamic configuration entity |
| 689 | schema: |
| 690 | type: string |
| 691 | - name: path |
| 692 | in: query |
| 693 | description: Top level path of the configuration entities, used with action 'tree' |
| 694 | schema: |
| 695 | type: string |
| 696 | default: '/' |
| 697 | - name: timeout |
| 698 | in: query |
| 699 | description: The timeout in seconds |
| 700 | schema: |
| 701 | type: number |
| 702 | default: 120 |
| 703 | responses: |
| 704 | "200": |
| 705 | description: The call was successful. |
| 706 | content: |
| 707 | application/json: |
| 708 | schema: |
| 709 | oneOf: |
| 710 | - $ref: '#/components/schemas/config_default_response' |
| 711 | - $ref: '#/components/schemas/config_tree' |
| 712 | - $ref: "#/components/schemas/config_schema" |
| 713 | "400": |
| 714 | description: Something is wrong with the request. |
| 715 | content: |
| 716 | application/json: |
| 717 | schema: |
| 718 | $ref: '#/components/schemas/config_default_response' |
| 719 | "404": |
| 720 | description: The configurable entity requests is not found. |
| 721 | content: |
| 722 | application/json: |
| 723 | schema: |
| 724 | $ref: '#/components/schemas/config_default_response' |
| 725 | post: |
| 726 | operationId: postConfig |
| 727 | tags: |
| 728 | - dyncfg |
| 729 | description: | |
| 730 | Post dynamic configuration to Netdata. |
| 731 | parameters: |
| 732 | - name: action |
| 733 | in: query |
| 734 | description: The type of action required. |
| 735 | schema: |
| 736 | type: string |
| 737 | enum: |
| 738 | - add |
| 739 | - test |
| 740 | - update |
| 741 | - name: id |
| 742 | in: query |
| 743 | description: The ID of the dynamic configuration entity to configure. |
| 744 | schema: |
| 745 | type: string |
| 746 | - name: name |
| 747 | in: query |
| 748 | description: Name of the dynamic configuration entity, used with action 'add' |
| 749 | schema: |
| 750 | type: string |
| 751 | - name: timeout |
| 752 | in: query |
| 753 | description: The timeout in seconds |
| 754 | schema: |
| 755 | type: number |
| 756 | default: 120 |
| 757 | responses: |
| 758 | "200": |
| 759 | description: The call was successful. This also means the configuration is currently running. |
| 760 | content: |
| 761 | application/json: |
| 762 | schema: |
| 763 | $ref: '#/components/schemas/config_default_response' |
| 764 | "202": |
| 765 | description: The call was successful. The configuration has been accepted, but its status is not yet known. |
| 766 | content: |
| 767 | application/json: |
| 768 | schema: |
| 769 | $ref: '#/components/schemas/config_default_response' |
| 770 | "299": |
| 771 | description: The call was successful. The configuration has been accepted, but a restart is required to apply it. |
| 772 | content: |
| 773 | application/json: |
| 774 | schema: |
| 775 | $ref: '#/components/schemas/config_default_response' |
| 776 | "400": |
| 777 | description: Something is wrong with the request. |
| 778 | content: |
| 779 | application/json: |
| 780 | schema: |
| 781 | $ref: '#/components/schemas/config_default_response' |
| 782 | "404": |
| 783 | description: The configurable entity requests is not found. |
| 784 | content: |
| 785 | application/json: |
| 786 | schema: |
| 787 | $ref: '#/components/schemas/config_default_response' |
| 788 | /api/v2/data: |
| 789 | get: |
| 790 | deprecated: true |
| 791 | operationId: dataQuery2 |
| 792 | tags: |
| 793 | - data |
| 794 | summary: Data Query v2 |
| 795 | description: | |
| 796 | Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation. |
| 797 | |
| 798 | **Security & Access Control:** |
| 799 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 800 | - **Default Access:** Public (no authentication required) |
| 801 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 802 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 803 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 804 | security: |
| 805 | - {} |
| 806 | - bearerAuth: [] |
| 807 | parameters: |
| 808 | - name: group_by |
| 809 | in: query |
| 810 | description: | |
| 811 | A comma separated list of the groupings required. |
| 812 | All possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored. |
| 813 | The order they are placed in the list is currently ignored. |
| 814 | This parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required. |
| 815 | required: false |
| 816 | schema: |
| 817 | type: array |
| 818 | items: |
| 819 | type: string |
| 820 | enum: |
| 821 | - dimension |
| 822 | - instance |
| 823 | - percentage-of-instance |
| 824 | - label |
| 825 | - node |
| 826 | - context |
| 827 | - units |
| 828 | - selected |
| 829 | default: |
| 830 | - dimension |
| 831 | - name: group_by_label |
| 832 | in: query |
| 833 | description: | |
| 834 | A comma separated list of the label keys to group by their values. The order of the labels in the list is respected. |
| 835 | This parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required. |
| 836 | required: false |
| 837 | schema: |
| 838 | type: string |
| 839 | format: comma separated list of label keys to group by |
| 840 | default: "" |
| 841 | - name: aggregation |
| 842 | in: query |
| 843 | description: | |
| 844 | The aggregation function to apply when grouping metrics together. |
| 845 | When option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average. |
| 846 | This parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required. |
| 847 | required: false |
| 848 | schema: |
| 849 | type: string |
| 850 | enum: |
| 851 | - min |
| 852 | - max |
| 853 | - avg |
| 854 | - average |
| 855 | - sum |
| 856 | - percentage |
| 857 | - extremes |
| 858 | default: average |
| 859 | - $ref: '#/components/parameters/scopeNodes' |
| 860 | - $ref: '#/components/parameters/scopeContexts' |
| 861 | - $ref: '#/components/parameters/scopeInstances' |
| 862 | - $ref: '#/components/parameters/scopeLabels' |
| 863 | - $ref: '#/components/parameters/scopeDimensions' |
| 864 | - $ref: '#/components/parameters/filterNodes' |
| 865 | - $ref: '#/components/parameters/filterContexts' |
| 866 | - $ref: '#/components/parameters/filterInstances' |
| 867 | - $ref: '#/components/parameters/filterLabels' |
| 868 | - $ref: '#/components/parameters/filterAlerts' |
| 869 | - $ref: '#/components/parameters/filterDimensions' |
| 870 | - $ref: '#/components/parameters/after' |
| 871 | - $ref: '#/components/parameters/before' |
| 872 | - $ref: '#/components/parameters/points' |
| 873 | - $ref: '#/components/parameters/tier' |
| 874 | - $ref: '#/components/parameters/dataQueryOptions' |
| 875 | - $ref: '#/components/parameters/dataTimeGroup2' |
| 876 | - $ref: '#/components/parameters/dataTimeGroupOptions2' |
| 877 | - $ref: '#/components/parameters/dataTimeResampling2' |
| 878 | - $ref: '#/components/parameters/dataFormat2' |
| 879 | - $ref: '#/components/parameters/cardinalityLimit' |
| 880 | - $ref: '#/components/parameters/timeoutMS' |
| 881 | - $ref: '#/components/parameters/callback' |
| 882 | - $ref: '#/components/parameters/filename' |
| 883 | - $ref: '#/components/parameters/tqx' |
| 884 | responses: |
| 885 | "200": |
| 886 | description: | |
| 887 | The call was successful. The response includes the data in the format requested. |
| 888 | content: |
| 889 | application/json: |
| 890 | schema: |
| 891 | oneOf: |
| 892 | - $ref: '#/components/schemas/jsonwrap2' |
| 893 | - $ref: '#/components/schemas/data_json_formats2' |
| 894 | text/plain: |
| 895 | schema: |
| 896 | type: string |
| 897 | format: according to the format requested. |
| 898 | text/html: |
| 899 | schema: |
| 900 | type: string |
| 901 | format: html |
| 902 | application/x-javascript: |
| 903 | schema: |
| 904 | type: string |
| 905 | format: javascript |
| 906 | "400": |
| 907 | description: | |
| 908 | Bad request - the body will include a message stating what is wrong. |
| 909 | "500": |
| 910 | description: | |
| 911 | Internal server error. This usually means the server is out of memory. |
| 912 | /api/v3/data: |
| 913 | get: |
| 914 | operationId: dataQuery3 |
| 915 | tags: |
| 916 | - data |
| 917 | summary: Data Query v3 |
| 918 | description: | |
| 919 | Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation. |
| 920 | |
| 921 | **Security & Access Control:** |
| 922 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 923 | - **Default Access:** Public (no authentication required) |
| 924 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 925 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 926 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 927 | security: |
| 928 | - {} |
| 929 | - bearerAuth: [] |
| 930 | parameters: |
| 931 | - name: group_by |
| 932 | in: query |
| 933 | description: | |
| 934 | A comma separated list of the groupings required. |
| 935 | All possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored. |
| 936 | The order they are placed in the list is currently ignored. |
| 937 | This parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required. |
| 938 | required: false |
| 939 | schema: |
| 940 | type: array |
| 941 | items: |
| 942 | type: string |
| 943 | enum: |
| 944 | - dimension |
| 945 | - instance |
| 946 | - percentage-of-instance |
| 947 | - label |
| 948 | - node |
| 949 | - context |
| 950 | - units |
| 951 | - selected |
| 952 | default: |
| 953 | - dimension |
| 954 | - name: group_by_label |
| 955 | in: query |
| 956 | description: | |
| 957 | A comma separated list of the label keys to group by their values. The order of the labels in the list is respected. |
| 958 | This parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required. |
| 959 | required: false |
| 960 | schema: |
| 961 | type: string |
| 962 | format: comma separated list of label keys to group by |
| 963 | default: "" |
| 964 | - name: aggregation |
| 965 | in: query |
| 966 | description: | |
| 967 | The aggregation function to apply when grouping metrics together. |
| 968 | When option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average. |
| 969 | This parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required. |
| 970 | required: false |
| 971 | schema: |
| 972 | type: string |
| 973 | enum: |
| 974 | - min |
| 975 | - max |
| 976 | - avg |
| 977 | - average |
| 978 | - sum |
| 979 | - percentage |
| 980 | - extremes |
| 981 | default: average |
| 982 | - $ref: '#/components/parameters/scopeNodes' |
| 983 | - $ref: '#/components/parameters/scopeContexts' |
| 984 | - $ref: '#/components/parameters/scopeInstances' |
| 985 | - $ref: '#/components/parameters/scopeLabels' |
| 986 | - $ref: '#/components/parameters/scopeDimensions' |
| 987 | - $ref: '#/components/parameters/filterNodes' |
| 988 | - $ref: '#/components/parameters/filterContexts' |
| 989 | - $ref: '#/components/parameters/filterInstances' |
| 990 | - $ref: '#/components/parameters/filterLabels' |
| 991 | - $ref: '#/components/parameters/filterAlerts' |
| 992 | - $ref: '#/components/parameters/filterDimensions' |
| 993 | - $ref: '#/components/parameters/after' |
| 994 | - $ref: '#/components/parameters/before' |
| 995 | - $ref: '#/components/parameters/points' |
| 996 | - $ref: '#/components/parameters/tier' |
| 997 | - $ref: '#/components/parameters/dataQueryOptions' |
| 998 | - $ref: '#/components/parameters/dataTimeGroup2' |
| 999 | - $ref: '#/components/parameters/dataTimeGroupOptions2' |
| 1000 | - $ref: '#/components/parameters/dataTimeResampling2' |
| 1001 | - $ref: '#/components/parameters/dataFormat2' |
| 1002 | - $ref: '#/components/parameters/cardinalityLimit' |
| 1003 | - $ref: '#/components/parameters/timeoutMS' |
| 1004 | - $ref: '#/components/parameters/callback' |
| 1005 | - $ref: '#/components/parameters/filename' |
| 1006 | - $ref: '#/components/parameters/tqx' |
| 1007 | responses: |
| 1008 | "200": |
| 1009 | description: | |
| 1010 | The call was successful. The response includes the data in the format requested. |
| 1011 | content: |
| 1012 | application/json: |
| 1013 | schema: |
| 1014 | oneOf: |
| 1015 | - $ref: '#/components/schemas/jsonwrap2' |
| 1016 | - $ref: '#/components/schemas/data_json_formats2' |
| 1017 | text/plain: |
| 1018 | schema: |
| 1019 | type: string |
| 1020 | format: according to the format requested. |
| 1021 | text/html: |
| 1022 | schema: |
| 1023 | type: string |
| 1024 | format: html |
| 1025 | application/x-javascript: |
| 1026 | schema: |
| 1027 | type: string |
| 1028 | format: javascript |
| 1029 | "400": |
| 1030 | description: | |
| 1031 | Bad request - the body will include a message stating what is wrong. |
| 1032 | "500": |
| 1033 | description: | |
| 1034 | Internal server error. This usually means the server is out of memory. |
| 1035 | /api/v1/data: |
| 1036 | get: |
| 1037 | deprecated: true |
| 1038 | operationId: dataQuery1 |
| 1039 | tags: |
| 1040 | - data |
| 1041 | summary: Data Query v1 - Single node, single chart or context queries. without group-by. |
| 1042 | description: | |
| 1043 | Query metric data of a chart or context of a node and return a dataset having time-series data for all dimensions available. |
| 1044 | For group-by functionality, use `/api/v2/data`. |
| 1045 | At least a `chart` or a `context` have to be given for the data query to be executed. |
| 1046 | |
| 1047 | **Security & Access Control:** |
| 1048 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 1049 | - **Default Access:** Public (no authentication required) |
| 1050 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 1051 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 1052 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 1053 | security: |
| 1054 | - {} |
| 1055 | - bearerAuth: [] |
| 1056 | parameters: |
| 1057 | - $ref: '#/components/parameters/chart' |
| 1058 | - $ref: '#/components/parameters/context' |
| 1059 | - $ref: '#/components/parameters/dimension' |
| 1060 | - $ref: '#/components/parameters/chart_label_key' |
| 1061 | - $ref: '#/components/parameters/chart_labels_filter' |
| 1062 | - $ref: '#/components/parameters/after' |
| 1063 | - $ref: '#/components/parameters/before' |
| 1064 | - $ref: '#/components/parameters/points' |
| 1065 | - $ref: '#/components/parameters/tier' |
| 1066 | - $ref: '#/components/parameters/dataQueryOptions' |
| 1067 | - $ref: '#/components/parameters/dataFormat1' |
| 1068 | - $ref: '#/components/parameters/dataTimeGroup1' |
| 1069 | - $ref: '#/components/parameters/dataTimeGroupOptions1' |
| 1070 | - $ref: '#/components/parameters/dataTimeResampling1' |
| 1071 | - $ref: '#/components/parameters/timeoutMS' |
| 1072 | - $ref: '#/components/parameters/callback' |
| 1073 | - $ref: '#/components/parameters/filename' |
| 1074 | - $ref: '#/components/parameters/tqx' |
| 1075 | responses: |
| 1076 | "200": |
| 1077 | description: | |
| 1078 | The call was successful. The response includes the data in the format requested. |
| 1079 | content: |
| 1080 | application/json: |
| 1081 | schema: |
| 1082 | oneOf: |
| 1083 | - $ref: '#/components/schemas/jsonwrap1' |
| 1084 | - $ref: '#/components/schemas/data_json_formats1' |
| 1085 | text/plain: |
| 1086 | schema: |
| 1087 | type: string |
| 1088 | format: according to the format requested. |
| 1089 | text/html: |
| 1090 | schema: |
| 1091 | type: string |
| 1092 | format: html |
| 1093 | application/x-javascript: |
| 1094 | schema: |
| 1095 | type: string |
| 1096 | format: javascript |
| 1097 | "400": |
| 1098 | description: Bad request - the body will include a message stating what is wrong. |
| 1099 | "404": |
| 1100 | description: Chart or context is not found. The supplied chart or context will be reported. |
| 1101 | "500": |
| 1102 | description: Internal server error. This usually means the server is out of |
| 1103 | memory. |
| 1104 | /api/v1/allmetrics: |
| 1105 | get: |
| 1106 | deprecated: true |
| 1107 | operationId: allMetrics1 |
| 1108 | tags: |
| 1109 | - data |
| 1110 | summary: All Metrics v1 - Fetch latest value for all metrics |
| 1111 | description: | |
| 1112 | The `allmetrics` endpoint returns the latest value of all metrics maintained for a netdata node. |
| 1113 | |
| 1114 | **Security & Access Control:** |
| 1115 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 1116 | - **Default Access:** Public (no authentication required) |
| 1117 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 1118 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 1119 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 1120 | security: |
| 1121 | - {} |
| 1122 | - bearerAuth: [] |
| 1123 | parameters: |
| 1124 | - name: format |
| 1125 | in: query |
| 1126 | description: The format of the response to be returned. |
| 1127 | required: true |
| 1128 | schema: |
| 1129 | type: string |
| 1130 | enum: |
| 1131 | - shell |
| 1132 | - prometheus |
| 1133 | - prometheus_all_hosts |
| 1134 | - json |
| 1135 | default: shell |
| 1136 | - name: filter |
| 1137 | in: query |
| 1138 | description: Allows to filter charts out using simple patterns. |
| 1139 | required: false |
| 1140 | schema: |
| 1141 | type: string |
| 1142 | format: any text |
| 1143 | - name: variables |
| 1144 | in: query |
| 1145 | description: | |
| 1146 | When enabled, netdata will expose various system configuration variables. |
| 1147 | required: false |
| 1148 | schema: |
| 1149 | type: string |
| 1150 | enum: |
| 1151 | - yes |
| 1152 | - no |
| 1153 | default: no |
| 1154 | - name: timestamps |
| 1155 | in: query |
| 1156 | description: | |
| 1157 | Enable or disable timestamps in prometheus output. |
| 1158 | required: false |
| 1159 | schema: |
| 1160 | type: string |
| 1161 | enum: |
| 1162 | - yes |
| 1163 | - no |
| 1164 | default: yes |
| 1165 | - name: names |
| 1166 | in: query |
| 1167 | description: | |
| 1168 | When enabled netdata will report dimension names. When disabled netdata will report dimension IDs. The default is controlled in netdata.conf. |
| 1169 | required: false |
| 1170 | schema: |
| 1171 | type: string |
| 1172 | enum: |
| 1173 | - yes |
| 1174 | - no |
| 1175 | default: yes |
| 1176 | - name: oldunits |
| 1177 | in: query |
| 1178 | description: | |
| 1179 | When enabled, netdata will show metric names for the default `source=average` as they appeared before 1.12, by using the legacy unit naming conventions. |
| 1180 | required: false |
| 1181 | schema: |
| 1182 | type: string |
| 1183 | enum: |
| 1184 | - yes |
| 1185 | - no |
| 1186 | default: yes |
| 1187 | - name: hideunits |
| 1188 | in: query |
| 1189 | description: | |
| 1190 | When enabled, netdata will not include the units in the metric names, for the default `source=average`. |
| 1191 | required: false |
| 1192 | schema: |
| 1193 | type: string |
| 1194 | enum: |
| 1195 | - yes |
| 1196 | - no |
| 1197 | default: yes |
| 1198 | - name: server |
| 1199 | in: query |
| 1200 | description: | |
| 1201 | Set a distinct name of the client querying prometheus metrics. Netdata will use the client IP if this is not set. |
| 1202 | required: false |
| 1203 | schema: |
| 1204 | type: string |
| 1205 | format: any text |
| 1206 | - name: prefix |
| 1207 | in: query |
| 1208 | description: | |
| 1209 | Prefix all prometheus metrics with this string. |
| 1210 | required: false |
| 1211 | schema: |
| 1212 | type: string |
| 1213 | format: any text |
| 1214 | - name: data |
| 1215 | in: query |
| 1216 | description: | |
| 1217 | Select the prometheus response data source. There is a setting in netdata.conf for the default. |
| 1218 | required: false |
| 1219 | schema: |
| 1220 | type: string |
| 1221 | enum: |
| 1222 | - as-collected |
| 1223 | - average |
| 1224 | - sum |
| 1225 | default: average |
| 1226 | responses: |
| 1227 | "200": |
| 1228 | description: All the metrics returned in the format requested. |
| 1229 | "400": |
| 1230 | description: The format requested is not supported. |
| 1231 | /api/v1/badge.svg: |
| 1232 | get: |
| 1233 | deprecated: true |
| 1234 | operationId: badge1 |
| 1235 | tags: |
| 1236 | - badges |
| 1237 | summary: Generate a badge in form of SVG image for a chart (or dimension) |
| 1238 | description: Successful responses are SVG images. |
| 1239 | |
| 1240 | **Security & Access Control:** |
| 1241 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 1242 | - **Default Access:** Public (no authentication required) |
| 1243 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 1244 | - **IP Restrictions:** Subject to `allow badges from` in netdata.conf |
| 1245 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 1246 | security: |
| 1247 | - {} |
| 1248 | - bearerAuth: [] |
| 1249 | parameters: |
| 1250 | - $ref: '#/components/parameters/chart' |
| 1251 | - $ref: '#/components/parameters/dimension' |
| 1252 | - $ref: '#/components/parameters/after' |
| 1253 | - $ref: '#/components/parameters/before' |
| 1254 | - $ref: '#/components/parameters/dataTimeGroup1' |
| 1255 | - $ref: '#/components/parameters/dataQueryOptions' |
| 1256 | - name: alarm |
| 1257 | in: query |
| 1258 | description: The name of an alarm linked to the chart. |
| 1259 | required: false |
| 1260 | allowEmptyValue: true |
| 1261 | schema: |
| 1262 | type: string |
| 1263 | format: any text |
| 1264 | - name: label |
| 1265 | in: query |
| 1266 | description: A text to be used as the label. |
| 1267 | required: false |
| 1268 | allowEmptyValue: true |
| 1269 | schema: |
| 1270 | type: string |
| 1271 | format: any text |
| 1272 | - name: units |
| 1273 | in: query |
| 1274 | description: A text to be used as the units. |
| 1275 | required: false |
| 1276 | allowEmptyValue: true |
| 1277 | schema: |
| 1278 | type: string |
| 1279 | format: any text |
| 1280 | - name: label_color |
| 1281 | in: query |
| 1282 | description: | |
| 1283 | A color to be used for the background of the label side(left side) of the badge. One of predefined colors or specific color in hex `RGB` or `RRGGBB` format (without preceding `#` character). If value wrong or not given default color will be used. |
| 1284 | required: false |
| 1285 | allowEmptyValue: true |
| 1286 | schema: |
| 1287 | oneOf: |
| 1288 | - type: string |
| 1289 | enum: |
| 1290 | - green |
| 1291 | - brightgreen |
| 1292 | - yellow |
| 1293 | - yellowgreen |
| 1294 | - orange |
| 1295 | - red |
| 1296 | - blue |
| 1297 | - grey |
| 1298 | - gray |
| 1299 | - lightgrey |
| 1300 | - lightgray |
| 1301 | - type: string |
| 1302 | format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ |
| 1303 | - name: value_color |
| 1304 | in: query |
| 1305 | description: | |
| 1306 | A color to be used for the background of the value *(right)* part of badge. You can set multiple using a pipe with a condition each, like this: `color<value|color:null` The following operators are supported: >, <, >=, <=, =, :null (to check if no value exists). Each color can be specified in same manner as for `label_color` parameter. Currently only integers are supported as values. |
| 1307 | required: false |
| 1308 | allowEmptyValue: true |
| 1309 | schema: |
| 1310 | type: string |
| 1311 | format: any text |
| 1312 | - name: text_color_lbl |
| 1313 | in: query |
| 1314 | description: | |
| 1315 | Font color for label *(left)* part of the badge. One of predefined colors or as HTML hexadecimal color without preceding `#` character. Formats allowed `RGB` or `RRGGBB`. If no or wrong value given default color will be used. |
| 1316 | required: false |
| 1317 | allowEmptyValue: true |
| 1318 | schema: |
| 1319 | oneOf: |
| 1320 | - type: string |
| 1321 | enum: |
| 1322 | - green |
| 1323 | - brightgreen |
| 1324 | - yellow |
| 1325 | - yellowgreen |
| 1326 | - orange |
| 1327 | - red |
| 1328 | - blue |
| 1329 | - grey |
| 1330 | - gray |
| 1331 | - lightgrey |
| 1332 | - lightgray |
| 1333 | - type: string |
| 1334 | format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ |
| 1335 | - name: text_color_val |
| 1336 | in: query |
| 1337 | description: | |
| 1338 | Font color for value *(right)* part of the badge. One of predefined colors or as HTML hexadecimal color without preceding `#` character. Formats allowed `RGB` or `RRGGBB`. If no or wrong value given default color will be used. |
| 1339 | required: false |
| 1340 | allowEmptyValue: true |
| 1341 | schema: |
| 1342 | oneOf: |
| 1343 | - type: string |
| 1344 | enum: |
| 1345 | - green |
| 1346 | - brightgreen |
| 1347 | - yellow |
| 1348 | - yellowgreen |
| 1349 | - orange |
| 1350 | - red |
| 1351 | - blue |
| 1352 | - grey |
| 1353 | - gray |
| 1354 | - lightgrey |
| 1355 | - lightgray |
| 1356 | - type: string |
| 1357 | format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ |
| 1358 | - name: multiply |
| 1359 | in: query |
| 1360 | description: Multiply the value with this number for rendering it at the image |
| 1361 | (integer value required). |
| 1362 | required: false |
| 1363 | allowEmptyValue: true |
| 1364 | schema: |
| 1365 | type: number |
| 1366 | format: integer |
| 1367 | - name: divide |
| 1368 | in: query |
| 1369 | description: Divide the value with this number for rendering it at the image |
| 1370 | (integer value required). |
| 1371 | required: false |
| 1372 | allowEmptyValue: true |
| 1373 | schema: |
| 1374 | type: number |
| 1375 | format: integer |
| 1376 | - name: scale |
| 1377 | in: query |
| 1378 | description: Set the scale of the badge (greater or equal to 100). |
| 1379 | required: false |
| 1380 | allowEmptyValue: true |
| 1381 | schema: |
| 1382 | type: number |
| 1383 | format: integer |
| 1384 | - name: fixed_width_lbl |
| 1385 | in: query |
| 1386 | description: | |
| 1387 | This parameter overrides auto-sizing of badge and creates it with fixed width. This parameter determines the size of the label's left side *(label/name)*. You must set this parameter together with `fixed_width_val` otherwise it will be ignored. You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you're requesting. In case the text cannot fit the space given it will be clipped. The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`. |
| 1388 | required: false |
| 1389 | allowEmptyValue: false |
| 1390 | schema: |
| 1391 | type: number |
| 1392 | format: integer |
| 1393 | - name: fixed_width_val |
| 1394 | in: query |
| 1395 | description: | |
| 1396 | This parameter overrides auto-sizing of badge and creates it with fixed width. This parameter determines the size of the label's right side *(value)*. You must set this parameter together with `fixed_width_lbl` otherwise it will be ignored. You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you're requesting. In case the text cannot fit the space given it will be clipped. The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`. |
| 1397 | required: false |
| 1398 | allowEmptyValue: false |
| 1399 | schema: |
| 1400 | type: number |
| 1401 | format: integer |
| 1402 | - name: points |
| 1403 | in: query |
| 1404 | description: The number of points to use for the calculation. Default is 1. |
| 1405 | required: false |
| 1406 | allowEmptyValue: true |
| 1407 | schema: |
| 1408 | type: integer |
| 1409 | default: 1 |
| 1410 | - name: group_options |
| 1411 | in: query |
| 1412 | description: Additional options for the grouping function. |
| 1413 | required: false |
| 1414 | allowEmptyValue: true |
| 1415 | schema: |
| 1416 | type: string |
| 1417 | - name: precision |
| 1418 | in: query |
| 1419 | description: Number of decimal places to show in the value. Default is -1 (automatic). |
| 1420 | required: false |
| 1421 | allowEmptyValue: true |
| 1422 | schema: |
| 1423 | type: integer |
| 1424 | default: -1 |
| 1425 | - name: refresh |
| 1426 | in: query |
| 1427 | description: | |
| 1428 | Auto-refresh interval in seconds. Use "auto" to automatically determine refresh interval based on the time range or alarm update frequency. For alarms, defaults to the alarm's update_every. For charts with RRDR_OPTION_NOT_ALIGNED, defaults to the chart's update_every. Otherwise calculated from the time range (before - after). |
| 1429 | required: false |
| 1430 | allowEmptyValue: true |
| 1431 | schema: |
| 1432 | oneOf: |
| 1433 | - type: string |
| 1434 | enum: [auto] |
| 1435 | - type: integer |
| 1436 | minimum: 0 |
| 1437 | responses: |
| 1438 | "200": |
| 1439 | description: The call was successful. The response should be an SVG image. |
| 1440 | "400": |
| 1441 | description: Bad request - the body will include a message stating what is wrong. |
| 1442 | "404": |
| 1443 | description: No chart with the given id is found. |
| 1444 | "500": |
| 1445 | description: Internal server error. This usually means the server is out of |
| 1446 | memory. |
| 1447 | /api/v3/badge.svg: |
| 1448 | get: |
| 1449 | operationId: badge3 |
| 1450 | tags: |
| 1451 | - badges |
| 1452 | summary: Generate a badge in form of SVG image for a chart (or dimension) - Latest API |
| 1453 | description: | |
| 1454 | Generates an SVG badge displaying real-time metric values from Netdata charts or alarms. |
| 1455 | This is the latest version (v3) of the badge API. It provides the same functionality as v1 but may include additional features in the future. |
| 1456 | |
| 1457 | The badge can display: |
| 1458 | - Current value of a chart dimension |
| 1459 | - Current status and value of an alarm |
| 1460 | - Custom labels and units |
| 1461 | - Dynamic colors based on value thresholds or alarm status |
| 1462 | |
| 1463 | Successful responses are SVG images that can be embedded in web pages or documentation. |
| 1464 | |
| 1465 | **Security & Access Control:** |
| 1466 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 1467 | - **Default Access:** Public (no authentication required) |
| 1468 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 1469 | - **IP Restrictions:** Subject to `allow badges from` in netdata.conf |
| 1470 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 1471 | security: |
| 1472 | - {} |
| 1473 | - bearerAuth: [] |
| 1474 | parameters: |
| 1475 | - $ref: '#/components/parameters/chart' |
| 1476 | - $ref: '#/components/parameters/dimension' |
| 1477 | - $ref: '#/components/parameters/after' |
| 1478 | - $ref: '#/components/parameters/before' |
| 1479 | - $ref: '#/components/parameters/dataTimeGroup1' |
| 1480 | - $ref: '#/components/parameters/dataQueryOptions' |
| 1481 | - name: alarm |
| 1482 | in: query |
| 1483 | description: The name of an alarm linked to the chart. When specified, the badge will display the alarm's current value and use alarm status for color selection. |
| 1484 | required: false |
| 1485 | allowEmptyValue: true |
| 1486 | schema: |
| 1487 | type: string |
| 1488 | - name: label |
| 1489 | in: query |
| 1490 | description: | |
| 1491 | Custom text to use as the badge label (left side). If not specified: |
| 1492 | - For alarms: uses the alarm name (with underscores replaced by spaces) |
| 1493 | - For dimensions: uses the dimension name |
| 1494 | - Otherwise: uses the chart name |
| 1495 | required: false |
| 1496 | allowEmptyValue: true |
| 1497 | schema: |
| 1498 | type: string |
| 1499 | - name: units |
| 1500 | in: query |
| 1501 | description: | |
| 1502 | Custom text to use as the units suffix. If not specified: |
| 1503 | - For alarms: uses the alarm's configured units or empty string |
| 1504 | - For percentage queries: uses "%" |
| 1505 | - Otherwise: uses the chart's units |
| 1506 | required: false |
| 1507 | allowEmptyValue: true |
| 1508 | schema: |
| 1509 | type: string |
| 1510 | - name: label_color |
| 1511 | in: query |
| 1512 | description: | |
| 1513 | Background color for the label (left) side of the badge. Can be: |
| 1514 | - One of the predefined color names |
| 1515 | - Hex RGB format (3 digits): e.g., "f00" for red |
| 1516 | - Hex RRGGBB format (6 digits): e.g., "ff0000" for red |
| 1517 | Note: Do not include the '#' character. If value is invalid, default color will be used. |
| 1518 | required: false |
| 1519 | allowEmptyValue: true |
| 1520 | schema: |
| 1521 | oneOf: |
| 1522 | - type: string |
| 1523 | enum: [green, brightgreen, yellow, yellowgreen, orange, red, blue, grey, gray, lightgrey, lightgray] |
| 1524 | - type: string |
| 1525 | format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ |
| 1526 | - name: value_color |
| 1527 | in: query |
| 1528 | description: | |
| 1529 | Background color for the value (right) side of the badge. Supports conditional coloring based on the value. |
| 1530 | |
| 1531 | Can be specified as: |
| 1532 | - Simple color: Same format as label_color |
| 1533 | - Conditional: Multiple color rules separated by pipe (|), each with format: `color<operator>value` |
| 1534 | |
| 1535 | Supported operators: |
| 1536 | - `>`: greater than |
| 1537 | - `<`: less than |
| 1538 | - `>=`: greater than or equal |
| 1539 | - `<=`: less than or equal |
| 1540 | - `=`: equal to |
| 1541 | - `:null`: true when no value exists |
| 1542 | |
| 1543 | Example: `green<80|yellow<95|red` (green if value < 80, yellow if < 95, otherwise red) |
| 1544 | |
| 1545 | Note: Currently only integers are supported as values. Colors follow same format as label_color. |
| 1546 | required: false |
| 1547 | allowEmptyValue: true |
| 1548 | schema: |
| 1549 | type: string |
| 1550 | - name: text_color_lbl |
| 1551 | in: query |
| 1552 | description: | |
| 1553 | Font color for the label (left) side text. Can be: |
| 1554 | - One of the predefined color names |
| 1555 | - Hex RGB or RRGGBB format without '#' character |
| 1556 | If not specified or invalid, default color will be used. |
| 1557 | required: false |
| 1558 | allowEmptyValue: true |
| 1559 | schema: |
| 1560 | oneOf: |
| 1561 | - type: string |
| 1562 | enum: [green, brightgreen, yellow, yellowgreen, orange, red, blue, grey, gray, lightgrey, lightgray] |
| 1563 | - type: string |
| 1564 | format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ |
| 1565 | - name: text_color_val |
| 1566 | in: query |
| 1567 | description: | |
| 1568 | Font color for the value (right) side text. Can be: |
| 1569 | - One of the predefined color names |
| 1570 | - Hex RGB or RRGGBB format without '#' character |
| 1571 | If not specified or invalid, default color will be used. |
| 1572 | required: false |
| 1573 | allowEmptyValue: true |
| 1574 | schema: |
| 1575 | oneOf: |
| 1576 | - type: string |
| 1577 | enum: [green, brightgreen, yellow, yellowgreen, orange, red, blue, grey, gray, lightgrey, lightgray] |
| 1578 | - type: string |
| 1579 | format: ^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ |
| 1580 | - name: multiply |
| 1581 | in: query |
| 1582 | description: | |
| 1583 | Multiply the displayed value by this number before rendering. Integer value required. |
| 1584 | Useful for unit conversions or scaling. Default is 1. |
| 1585 | required: false |
| 1586 | allowEmptyValue: true |
| 1587 | schema: |
| 1588 | type: integer |
| 1589 | default: 1 |
| 1590 | - name: divide |
| 1591 | in: query |
| 1592 | description: | |
| 1593 | Divide the displayed value by this number before rendering. Integer value required. |
| 1594 | Useful for unit conversions or scaling. Default is 1. |
| 1595 | required: false |
| 1596 | allowEmptyValue: true |
| 1597 | schema: |
| 1598 | type: integer |
| 1599 | default: 1 |
| 1600 | - name: scale |
| 1601 | in: query |
| 1602 | description: | |
| 1603 | Scale factor for the badge size as a percentage. Must be >= 100. |
| 1604 | - 100 = normal size (default) |
| 1605 | - 150 = 1.5x larger |
| 1606 | - 200 = 2x larger |
| 1607 | required: false |
| 1608 | allowEmptyValue: true |
| 1609 | schema: |
| 1610 | type: integer |
| 1611 | minimum: 100 |
| 1612 | default: 100 |
| 1613 | - name: fixed_width_lbl |
| 1614 | in: query |
| 1615 | description: | |
| 1616 | Fixed width for the label (left) side in pixels. Must be used together with `fixed_width_val`. |
| 1617 | |
| 1618 | This overrides automatic sizing and creates a badge with fixed dimensions. Ensure the width is sufficient for your content - text that doesn't fit will be clipped. |
| 1619 | |
| 1620 | The `scale` parameter still applies to these fixed width values. |
| 1621 | required: false |
| 1622 | allowEmptyValue: false |
| 1623 | schema: |
| 1624 | type: integer |
| 1625 | - name: fixed_width_val |
| 1626 | in: query |
| 1627 | description: | |
| 1628 | Fixed width for the value (right) side in pixels. Must be used together with `fixed_width_lbl`. |
| 1629 | |
| 1630 | This overrides automatic sizing and creates a badge with fixed dimensions. Ensure the width is sufficient for your content - text that doesn't fit will be clipped. |
| 1631 | |
| 1632 | The `scale` parameter still applies to these fixed width values. |
| 1633 | required: false |
| 1634 | allowEmptyValue: false |
| 1635 | schema: |
| 1636 | type: integer |
| 1637 | - name: points |
| 1638 | in: query |
| 1639 | description: | |
| 1640 | Number of data points to use for the calculation. Default is 1. |
| 1641 | Higher values provide averaging over more samples. |
| 1642 | required: false |
| 1643 | allowEmptyValue: true |
| 1644 | schema: |
| 1645 | type: integer |
| 1646 | default: 1 |
| 1647 | - name: group_options |
| 1648 | in: query |
| 1649 | description: Additional options for the time-series grouping function. Format depends on the selected group method. |
| 1650 | required: false |
| 1651 | allowEmptyValue: true |
| 1652 | schema: |
| 1653 | type: string |
| 1654 | - name: precision |
| 1655 | in: query |
| 1656 | description: | |
| 1657 | Number of decimal places to display in the value. |
| 1658 | - Positive number: exact decimal places (e.g., 2 = "12.34") |
| 1659 | - -1 (default): automatic precision based on value magnitude |
| 1660 | required: false |
| 1661 | allowEmptyValue: true |
| 1662 | schema: |
| 1663 | type: integer |
| 1664 | default: -1 |
| 1665 | - name: refresh |
| 1666 | in: query |
| 1667 | description: | |
| 1668 | Auto-refresh interval for the badge. Can be: |
| 1669 | - "auto": Automatically determine refresh based on context |
| 1670 | - For alarms: uses the alarm's update_every interval |
| 1671 | - For non-aligned charts: uses the chart's update_every |
| 1672 | - For time-range queries: uses the query time span |
| 1673 | - Integer: Specific refresh interval in seconds |
| 1674 | |
| 1675 | When refresh is set, the response includes a Refresh HTTP header. |
| 1676 | required: false |
| 1677 | allowEmptyValue: true |
| 1678 | schema: |
| 1679 | oneOf: |
| 1680 | - type: string |
| 1681 | enum: [auto] |
| 1682 | - type: integer |
| 1683 | minimum: 0 |
| 1684 | responses: |
| 1685 | "200": |
| 1686 | description: | |
| 1687 | Success. The response is an SVG image that can be embedded in HTML or Markdown. |
| 1688 | |
| 1689 | When refresh parameter is set, the response includes: |
| 1690 | - Refresh header with the interval |
| 1691 | - Appropriate Cache-Control headers |
| 1692 | content: |
| 1693 | image/svg+xml: |
| 1694 | schema: |
| 1695 | type: string |
| 1696 | format: binary |
| 1697 | "400": |
| 1698 | description: | |
| 1699 | Bad request. The response body contains an error message explaining what is wrong. |
| 1700 | Common causes: |
| 1701 | - Missing required 'chart' parameter |
| 1702 | - Invalid parameter values |
| 1703 | "404": |
| 1704 | description: | |
| 1705 | Not found. Possible causes: |
| 1706 | - Chart with the specified ID does not exist |
| 1707 | - Specified alarm does not exist on the chart |
| 1708 | "500": |
| 1709 | description: Internal server error. Usually indicates the server is out of memory. |
| 1710 | /api/v3/allmetrics: |
| 1711 | get: |
| 1712 | operationId: allMetrics3 |
| 1713 | tags: |
| 1714 | - data |
| 1715 | summary: All Metrics v3 - Export all metrics in various formats - Latest API |
| 1716 | description: | |
| 1717 | The `allmetrics` endpoint exports the latest values of all metrics collected by Netdata in various formats suitable for integration with external monitoring systems, shell scripts, or APIs. |
| 1718 | |
| 1719 | This is the latest version (v3) of the allmetrics API. It provides the same functionality as v1 but may include additional features in the future. |
| 1720 | |
| 1721 | **Supported Export Formats:** |
| 1722 | - **shell**: Bash-compatible variable assignments for scripting (NETDATA_CHARTNAME_DIMENSIONNAME="value") |
| 1723 | - **prometheus**: Prometheus exposition format for a single host |
| 1724 | - **prometheus_all_hosts**: Prometheus format including metrics from all child nodes |
| 1725 | - **json**: JSON format with full chart and dimension metadata |
| 1726 | |
| 1727 | **Use Cases:** |
| 1728 | - Integration with Prometheus or other metric collectors |
| 1729 | - Shell script automation and monitoring |
| 1730 | - Custom metric exporters |
| 1731 | - Multi-host metric aggregation |
| 1732 | |
| 1733 | **Security & Access Control:** |
| 1734 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 1735 | - **Default Access:** Public (no authentication required) |
| 1736 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 1737 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 1738 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 1739 | security: |
| 1740 | - {} |
| 1741 | - bearerAuth: [] |
| 1742 | parameters: |
| 1743 | - name: format |
| 1744 | in: query |
| 1745 | description: | |
| 1746 | The export format for the metrics. Required parameter. |
| 1747 | |
| 1748 | **Formats:** |
| 1749 | - `shell`: Bash variables (default) - Exports as NETDATA_CHARTNAME_DIMENSIONNAME="value" |
| 1750 | - `prometheus`: Prometheus format (single host) - Compatible with Prometheus scraping |
| 1751 | - `prometheus_all_hosts`: Prometheus format (all hosts) - Includes metrics from child nodes with host labels |
| 1752 | - `json`: JSON format - Full metadata including chart names, families, contexts, units, and timestamps |
| 1753 | |
| 1754 | **Format Details:** |
| 1755 | - Shell format includes alarm status variables (NETDATA_ALARM_CHART_ALARM_STATUS, NETDATA_ALARM_CHART_ALARM_VALUE) |
| 1756 | - Prometheus formats respect Prometheus metric naming conventions |
| 1757 | - JSON format provides complete chart and dimension information |
| 1758 | required: true |
| 1759 | schema: |
| 1760 | type: string |
| 1761 | enum: |
| 1762 | - shell |
| 1763 | - prometheus |
| 1764 | - prometheus_all_hosts |
| 1765 | - json |
| 1766 | default: shell |
| 1767 | - name: filter |
| 1768 | in: query |
| 1769 | description: | |
| 1770 | Simple pattern filter to include only specific charts. Uses Netdata simple pattern matching. |
| 1771 | |
| 1772 | **Pattern Syntax:** |
| 1773 | - Exact match: `system.cpu` |
| 1774 | - Wildcard: `system.*` (all system charts) |
| 1775 | - Multiple patterns: `system.* disk.*` (space-separated) |
| 1776 | - Negation: `!system.cpu` (exclude specific chart) |
| 1777 | |
| 1778 | When not specified, all charts are exported. |
| 1779 | |
| 1780 | **Examples:** |
| 1781 | - `system.*` - Export only system charts |
| 1782 | - `disk.* net.*` - Export disk and network charts |
| 1783 | - `* !*.mdstat` - Export all except mdstat charts |
| 1784 | required: false |
| 1785 | schema: |
| 1786 | type: string |
| 1787 | - name: variables |
| 1788 | in: query |
| 1789 | description: | |
| 1790 | **Prometheus format only**: Include or exclude system configuration variables in the output. |
| 1791 | |
| 1792 | When enabled (yes/1/true), Netdata exposes various system configuration variables as Prometheus metrics. This includes: |
| 1793 | - Netdata configuration parameters |
| 1794 | - System environment information |
| 1795 | - Collection plugin states |
| 1796 | |
| 1797 | Note: Only affects Prometheus format output. Ignored for shell and json formats. |
| 1798 | required: false |
| 1799 | schema: |
| 1800 | type: string |
| 1801 | enum: |
| 1802 | - "yes" |
| 1803 | - "no" |
| 1804 | - "1" |
| 1805 | - "0" |
| 1806 | - "true" |
| 1807 | - "false" |
| 1808 | default: "no" |
| 1809 | - name: timestamps |
| 1810 | in: query |
| 1811 | description: | |
| 1812 | **Prometheus format only**: Include or exclude timestamps in Prometheus metrics. |
| 1813 | |
| 1814 | When enabled (default), each metric includes a timestamp of when it was collected. |
| 1815 | When disabled, metrics are exported without timestamps (Prometheus will use scrape time). |
| 1816 | |
| 1817 | Note: Only affects Prometheus format output. Ignored for shell and json formats. |
| 1818 | required: false |
| 1819 | schema: |
| 1820 | type: string |
| 1821 | enum: |
| 1822 | - "yes" |
| 1823 | - "no" |
| 1824 | - "1" |
| 1825 | - "0" |
| 1826 | - "true" |
| 1827 | - "false" |
| 1828 | default: "yes" |
| 1829 | - name: names |
| 1830 | in: query |
| 1831 | description: | |
| 1832 | **Prometheus format only**: Use dimension names vs IDs in metric names. |
| 1833 | |
| 1834 | When enabled (default), Prometheus metrics use human-readable dimension names. |
| 1835 | When disabled, metrics use dimension IDs (which never change). |
| 1836 | |
| 1837 | **Example:** |
| 1838 | - names=yes: `netdata_system_cpu_percentage_average{dimension="user"}` |
| 1839 | - names=no: `netdata_system_cpu_percentage_average{dimension="user"}` |
| 1840 | |
| 1841 | The default is controlled by the global Netdata configuration. This parameter allows per-request override. |
| 1842 | |
| 1843 | Note: Only affects Prometheus format output. |
| 1844 | required: false |
| 1845 | schema: |
| 1846 | type: string |
| 1847 | enum: |
| 1848 | - "yes" |
| 1849 | - "no" |
| 1850 | - "1" |
| 1851 | - "0" |
| 1852 | - "true" |
| 1853 | - "false" |
| 1854 | - name: oldunits |
| 1855 | in: query |
| 1856 | description: | |
| 1857 | **Prometheus format only**: Use legacy unit naming conventions (pre-1.12 format). |
| 1858 | |
| 1859 | When enabled, metric names for `source=average` use the old unit naming conventions as they appeared before Netdata version 1.12. |
| 1860 | |
| 1861 | This is provided for backward compatibility with existing Prometheus configurations. |
| 1862 | |
| 1863 | Note: Only affects Prometheus format with source=average. |
| 1864 | required: false |
| 1865 | schema: |
| 1866 | type: string |
| 1867 | enum: |
| 1868 | - "yes" |
| 1869 | - "no" |
| 1870 | - "1" |
| 1871 | - "0" |
| 1872 | - "true" |
| 1873 | - "false" |
| 1874 | default: "no" |
| 1875 | - name: hideunits |
| 1876 | in: query |
| 1877 | description: | |
| 1878 | **Prometheus format only**: Exclude units from metric names for source=average. |
| 1879 | |
| 1880 | When enabled, units are not included in the Prometheus metric names for the default `source=average` data. |
| 1881 | |
| 1882 | **Example:** |
| 1883 | - hideunits=no: `netdata_system_cpu_percentage_average` |
| 1884 | - hideunits=yes: `netdata_system_cpu_average` |
| 1885 | |
| 1886 | Note: Only affects Prometheus format with source=average. |
| 1887 | required: false |
| 1888 | schema: |
| 1889 | type: string |
| 1890 | enum: |
| 1891 | - "yes" |
| 1892 | - "no" |
| 1893 | - "1" |
| 1894 | - "0" |
| 1895 | - "true" |
| 1896 | - "false" |
| 1897 | default: "no" |
| 1898 | - name: server |
| 1899 | in: query |
| 1900 | description: | |
| 1901 | **Prometheus format only**: Set a custom identifier for the client scraping the metrics. |
| 1902 | |
| 1903 | This parameter is used to identify the client in Prometheus metric labels. If not specified, Netdata uses the client's IP address. |
| 1904 | |
| 1905 | Useful when multiple Prometheus instances scrape the same Netdata agent, or when scraping through a proxy. |
| 1906 | |
| 1907 | **Example:** `server=prometheus-prod-1` |
| 1908 | |
| 1909 | Note: Only affects Prometheus format output. This value appears in metric labels to distinguish scraping sources. |
| 1910 | required: false |
| 1911 | schema: |
| 1912 | type: string |
| 1913 | - name: prefix |
| 1914 | in: query |
| 1915 | description: | |
| 1916 | **Prometheus format only**: Prefix all Prometheus metric names with a custom string. |
| 1917 | |
| 1918 | Useful for namespacing metrics when aggregating from multiple sources or to comply with organizational metric naming conventions. |
| 1919 | |
| 1920 | **Example:** `prefix=mycompany_` produces metrics like `mycompany_system_cpu_percentage_average` |
| 1921 | |
| 1922 | The default prefix is controlled by the global Netdata configuration. This parameter allows per-request override. |
| 1923 | |
| 1924 | Note: Only affects Prometheus format output. |
| 1925 | required: false |
| 1926 | schema: |
| 1927 | type: string |
| 1928 | - name: data |
| 1929 | in: query |
| 1930 | description: | |
| 1931 | **Prometheus format only**: Select the data source/aggregation method for Prometheus metrics. |
| 1932 | |
| 1933 | **Options:** |
| 1934 | - `as-collected`: Raw values as collected by data collection plugins (no aggregation) |
| 1935 | - `average`: Average values over the collection interval (default) |
| 1936 | - `sum`: Sum of values over the collection interval |
| 1937 | |
| 1938 | The `as-collected` source provides the most recent raw sample, while `average` and `sum` provide values aggregated over the chart's update interval. |
| 1939 | |
| 1940 | The default is controlled by the global Netdata exporting configuration. This parameter allows per-request override. |
| 1941 | |
| 1942 | **Use Cases:** |
| 1943 | - `as-collected`: For counter metrics that Prometheus will rate() |
| 1944 | - `average`: For gauge metrics showing typical values |
| 1945 | - `sum`: For accumulating metrics |
| 1946 | |
| 1947 | Aliases: `source`, `data source`, `data-source`, `data_source`, `datasource` |
| 1948 | |
| 1949 | Note: Only affects Prometheus format output. |
| 1950 | required: false |
| 1951 | schema: |
| 1952 | type: string |
| 1953 | enum: |
| 1954 | - as-collected |
| 1955 | - average |
| 1956 | - sum |
| 1957 | default: average |
| 1958 | responses: |
| 1959 | "200": |
| 1960 | description: | |
| 1961 | Success. Metrics exported in the requested format. |
| 1962 | |
| 1963 | **Content Types:** |
| 1964 | - shell: text/plain |
| 1965 | - json: application/json |
| 1966 | - prometheus/prometheus_all_hosts: application/openmetrics-text (Prometheus format) |
| 1967 | |
| 1968 | **Response Characteristics:** |
| 1969 | - Shell format: Variables ready for sourcing in bash scripts |
| 1970 | - JSON format: Complete chart metadata with current values |
| 1971 | - Prometheus format: Ready for Prometheus scraping |
| 1972 | |
| 1973 | The response is not cacheable as it contains current metric values. |
| 1974 | content: |
| 1975 | text/plain: |
| 1976 | schema: |
| 1977 | type: string |
| 1978 | description: Shell format output (when format=shell) |
| 1979 | application/json: |
| 1980 | schema: |
| 1981 | type: object |
| 1982 | description: JSON format output (when format=json) |
| 1983 | application/openmetrics-text: |
| 1984 | schema: |
| 1985 | type: string |
| 1986 | description: Prometheus format output (when format=prometheus or prometheus_all_hosts) |
| 1987 | "400": |
| 1988 | description: | |
| 1989 | Bad request. The response body contains an error message. |
| 1990 | |
| 1991 | Common causes: |
| 1992 | - Invalid or missing 'format' parameter |
| 1993 | - Unsupported format value |
| 1994 | - Invalid filter pattern syntax |
| 1995 | "500": |
| 1996 | description: Internal server error. Usually indicates the server is out of memory or a collection plugin has crashed. |
| 1997 | /api/v3/alerts: |
| 1998 | get: |
| 1999 | operationId: alerts3 |
| 2000 | tags: |
| 2001 | - alerts |
| 2002 | summary: Current Alert Status - Multi-node Alert Information - Latest API |
| 2003 | description: | |
| 2004 | Returns the current status of all alerts across all nodes monitored by this Netdata agent. |
| 2005 | |
| 2006 | This is the latest version (v3) of the alerts API. It provides the same functionality as v2 but may include additional features in the future. |
| 2007 | |
| 2008 | **What This API Provides:** |
| 2009 | - Current state of all active, warning, and critical alerts |
| 2010 | - Alert values and thresholds |
| 2011 | - Alert configuration summaries |
| 2012 | - Multi-node alert aggregation |
| 2013 | - Filtering by alert name, context, node, or status |
| 2014 | |
| 2015 | **Use Cases:** |
| 2016 | - Dashboard alert widgets showing current system health |
| 2017 | - Alert management interfaces |
| 2018 | - Integration with external alerting systems |
| 2019 | - Monitoring alert coverage across infrastructure |
| 2020 | - Finding all alerts in specific states (warning/critical) |
| 2021 | |
| 2022 | **Response Content:** |
| 2023 | The response includes comprehensive information about alerts including their current values, configured thresholds, time in current state, and associated context/chart information. |
| 2024 | |
| 2025 | **Security & Access Control:** |
| 2026 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 2027 | - **Default Access:** Public (no authentication required) |
| 2028 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 2029 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 2030 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 2031 | security: |
| 2032 | - {} |
| 2033 | - bearerAuth: [] |
| 2034 | parameters: |
| 2035 | - $ref: '#/components/parameters/scopeNodes' |
| 2036 | - $ref: '#/components/parameters/scopeContexts' |
| 2037 | - $ref: '#/components/parameters/filterNodes' |
| 2038 | - $ref: '#/components/parameters/filterContexts' |
| 2039 | - name: alert |
| 2040 | in: query |
| 2041 | description: | |
| 2042 | Filter alerts by alert name pattern. Uses Netdata simple pattern matching. |
| 2043 | |
| 2044 | **Pattern Syntax:** |
| 2045 | - Exact match: `cpu_usage` |
| 2046 | - Wildcard: `cpu_*` (all CPU-related alerts) |
| 2047 | - Multiple patterns: `cpu_* ram_*` (space-separated) |
| 2048 | - Negation: `!cpu_usage` (all except this alert) |
| 2049 | |
| 2050 | **Common Alert Names:** |
| 2051 | - `ram_in_use` - RAM utilization |
| 2052 | - `disk_space_usage` - Disk space |
| 2053 | - `10min_cpu_usage` - CPU usage over 10 minutes |
| 2054 | - `tcp_listen_overflows` - TCP connection queue overflows |
| 2055 | - `disk_backlog` - Disk I/O backlog |
| 2056 | |
| 2057 | When not specified, all alerts are included. |
| 2058 | |
| 2059 | **Examples:** |
| 2060 | - `alert=ram_in_use` - Only RAM usage alert |
| 2061 | - `alert=*cpu*` - All CPU-related alerts |
| 2062 | - `alert=* !*_critical` - All alerts except those ending with _critical |
| 2063 | required: false |
| 2064 | schema: |
| 2065 | type: string |
| 2066 | examples: |
| 2067 | single: |
| 2068 | value: "ram_in_use" |
| 2069 | summary: Single alert |
| 2070 | pattern: |
| 2071 | value: "*cpu*" |
| 2072 | summary: All CPU alerts |
| 2073 | - name: status |
| 2074 | in: query |
| 2075 | description: | |
| 2076 | Filter alerts by their current status. Can specify multiple statuses. |
| 2077 | |
| 2078 | **Alert Statuses:** |
| 2079 | - `CRITICAL` - Alert is in critical state (highest severity) |
| 2080 | - `WARNING` - Alert is in warning state |
| 2081 | - `CLEAR` - Alert is in normal state (not triggered) |
| 2082 | - `UNDEFINED` - Alert could not be evaluated (e.g., division by zero, missing data) |
| 2083 | - `UNINITIALIZED` - Alert has not been evaluated yet (no data collected) |
| 2084 | |
| 2085 | **Multiple Statuses:** |
| 2086 | To show multiple statuses, separate them with commas: `status=CRITICAL,WARNING` |
| 2087 | |
| 2088 | **Use Cases:** |
| 2089 | - `status=CRITICAL` - Show only critical alerts requiring immediate attention |
| 2090 | - `status=CRITICAL,WARNING` - Show all alerts that need attention |
| 2091 | - `status=CLEAR` - Show alerts that are currently in normal state |
| 2092 | - Not specified - Show alerts in all states |
| 2093 | |
| 2094 | **Default:** When not specified, typically returns only alerts in WARNING or CRITICAL state (this depends on options parameter). |
| 2095 | required: false |
| 2096 | schema: |
| 2097 | type: string |
| 2098 | examples: |
| 2099 | critical_only: |
| 2100 | value: "CRITICAL" |
| 2101 | summary: Only critical alerts |
| 2102 | needs_attention: |
| 2103 | value: "CRITICAL,WARNING" |
| 2104 | summary: All alerts needing attention |
| 2105 | all_states: |
| 2106 | value: "CRITICAL,WARNING,CLEAR,UNDEFINED,UNINITIALIZED" |
| 2107 | summary: All alert states |
| 2108 | - name: options |
| 2109 | in: query |
| 2110 | description: | |
| 2111 | Comma or pipe-separated list of options to control response content. |
| 2112 | |
| 2113 | **Alert-Specific Options:** |
| 2114 | - `summary` - Include summary counters (total alerts, by status, by type) |
| 2115 | |
| 2116 | **General Options:** |
| 2117 | - `contexts` - Include context information |
| 2118 | - `instances` - Include alert instance details |
| 2119 | - `values` - Include current alert values |
| 2120 | - `configurations` - Include alert configuration details |
| 2121 | |
| 2122 | **Examples:** |
| 2123 | - `options=summary` - Include alert count summaries |
| 2124 | - `options=summary,values` - Summaries and current values |
| 2125 | - `options=summary|configurations` - Summaries and configs (pipe separator) |
| 2126 | |
| 2127 | When not specified, returns basic alert information without detailed configs or summaries. |
| 2128 | required: false |
| 2129 | schema: |
| 2130 | type: string |
| 2131 | examples: |
| 2132 | basic: |
| 2133 | value: "summary" |
| 2134 | summary: With summary counters |
| 2135 | detailed: |
| 2136 | value: "summary,values,configurations" |
| 2137 | summary: Complete alert information |
| 2138 | - $ref: '#/components/parameters/after' |
| 2139 | - $ref: '#/components/parameters/before' |
| 2140 | - name: timeout |
| 2141 | in: query |
| 2142 | description: | |
| 2143 | Maximum time in milliseconds to wait for the query to complete. |
| 2144 | |
| 2145 | This is useful for preventing long-running queries from blocking when querying large infrastructures with many nodes and alerts. |
| 2146 | |
| 2147 | **Format:** Integer (milliseconds) |
| 2148 | |
| 2149 | **Default:** Server default timeout (typically 30000ms = 30 seconds) |
| 2150 | |
| 2151 | **Examples:** |
| 2152 | - `timeout=5000` - 5 second timeout |
| 2153 | - `timeout=60000` - 60 second timeout |
| 2154 | |
| 2155 | When the timeout is exceeded, the server returns a partial result with whatever data was collected before the timeout. |
| 2156 | required: false |
| 2157 | schema: |
| 2158 | type: integer |
| 2159 | format: int64 |
| 2160 | minimum: 1000 |
| 2161 | example: 30000 |
| 2162 | - name: cardinality |
| 2163 | in: query |
| 2164 | description: | |
| 2165 | Limit the number of alert instances returned to prevent response explosion. |
| 2166 | |
| 2167 | When monitoring large infrastructures, some alert types may have hundreds or thousands of instances (e.g., disk space alerts for every disk on every node). |
| 2168 | |
| 2169 | This parameter limits the number of unique alert instances in the response. |
| 2170 | |
| 2171 | **Format:** Integer (maximum number of alert instances) |
| 2172 | |
| 2173 | **Default:** No limit |
| 2174 | |
| 2175 | **Use Cases:** |
| 2176 | - Preventing huge responses when there are many alert instances |
| 2177 | - Getting a sample of alerts rather than complete list |
| 2178 | - Dashboard widgets with limited display space |
| 2179 | |
| 2180 | **Example:** |
| 2181 | - `cardinality=100` - Return at most 100 alert instances |
| 2182 | |
| 2183 | **Alias:** Can also be specified as `cardinality_limit` |
| 2184 | |
| 2185 | When the limit is exceeded, the response may indicate how many alerts were omitted. |
| 2186 | required: false |
| 2187 | schema: |
| 2188 | type: integer |
| 2189 | minimum: 1 |
| 2190 | example: 100 |
| 2191 | responses: |
| 2192 | "200": |
| 2193 | description: | |
| 2194 | Success. Returns current alert status information. |
| 2195 | |
| 2196 | **Response Structure:** |
| 2197 | - Summary counters (when options=summary): counts by status, type, classification |
| 2198 | - Alert instances with their current states |
| 2199 | - Alert values and thresholds (when options=values) |
| 2200 | - Alert configurations (when options=configurations) |
| 2201 | - Node and context associations |
| 2202 | |
| 2203 | The response is grouped by contexts and includes metadata about each alert including its current status, value, time in current state, and associated chart/dimension. |
| 2204 | |
| 2205 | **Response Characteristics:** |
| 2206 | - JSON format |
| 2207 | - Not cacheable (alerts change frequently) |
| 2208 | - May include partial results if timeout is exceeded |
| 2209 | - Cardinality-limited if specified |
| 2210 | content: |
| 2211 | application/json: |
| 2212 | schema: |
| 2213 | type: object |
| 2214 | description: Multi-node alert status information |
| 2215 | "400": |
| 2216 | description: | |
| 2217 | Bad request. Common causes: |
| 2218 | - Invalid parameter values |
| 2219 | - Malformed filter patterns |
| 2220 | - Invalid status values |
| 2221 | - Invalid timeout or cardinality values |
| 2222 | "500": |
| 2223 | description: Internal server error. Usually indicates the server is out of memory. |
| 2224 | /api/v3/alert_transitions: |
| 2225 | get: |
| 2226 | operationId: alert_transitions_v3 |
| 2227 | tags: |
| 2228 | - alerts |
| 2229 | summary: Retrieve alert state transition history across all nodes with advanced filtering |
| 2230 | description: | |
| 2231 | Returns the historical record of alert state changes (transitions) across the monitored infrastructure. This endpoint provides detailed information about when alerts changed state (e.g., from CLEAR to WARNING to CRITICAL), allowing you to analyze alert patterns, investigate incidents, and understand system behavior over time. |
| 2232 | |
| 2233 | **What is an Alert Transition?** |
| 2234 | An alert transition is a record of an alert changing from one state to another. Each transition includes: |
| 2235 | - Previous and new alert status (CLEAR, WARNING, CRITICAL, etc.) |
| 2236 | - When the transition occurred |
| 2237 | - How long the alert stayed in the previous state (duration) |
| 2238 | - Alert value at the time of transition |
| 2239 | - Complete alert metadata (name, context, node, etc.) |
| 2240 | |
| 2241 | **Key Features:** |
| 2242 | - **Multi-Node Support:** Query transitions across entire infrastructure |
| 2243 | - **Advanced Filtering:** Filter by status, type, component, role, node, alert name, context |
| 2244 | - **Faceted Search:** Use multiple filter facets simultaneously (e.g., "CRITICAL status on database nodes") |
| 2245 | - **Pagination:** Navigate through large result sets using anchor_gi |
| 2246 | - **Time Range:** Specify exact time windows for historical analysis |
| 2247 | |
| 2248 | **Use Cases:** |
| 2249 | - Incident investigation: "What alerts fired during the outage?" |
| 2250 | - Alert pattern analysis: "How often does this alert transition to CRITICAL?" |
| 2251 | - Alert tuning: "Which alerts flap between states most frequently?" |
| 2252 | - Compliance reporting: "Show all CRITICAL alerts in the last 30 days" |
| 2253 | - Root cause analysis: "What changed before this alert fired?" |
| 2254 | |
| 2255 | **Faceted Filtering:** |
| 2256 | This endpoint supports 9 different facets for precise filtering: |
| 2257 | - f_status: Filter by alert status (CRITICAL, WARNING, etc.) |
| 2258 | - f_type: Filter by alert type (e.g., "System", "Database", "Network") |
| 2259 | - f_role: Filter by recipient role (who should be notified) |
| 2260 | - f_class: Filter by alert classification |
| 2261 | - f_component: Filter by system component |
| 2262 | - f_node: Filter by specific node hostname |
| 2263 | - f_alert: Filter by alert name |
| 2264 | - f_instance: Filter by chart instance name |
| 2265 | - f_context: Filter by metric context |
| 2266 | |
| 2267 | **Examples:** |
| 2268 | 1. Recent critical transitions: `?last=100&f_status=CRITICAL` |
| 2269 | 2. Database alerts: `?f_component=Database&after=-86400` |
| 2270 | 3. Specific alert history: `?f_alert=disk_space_usage&last=50` |
| 2271 | 4. Node-specific transitions: `?f_node=web-server-01&after=-604800` |
| 2272 | |
| 2273 | **Response Format:** |
| 2274 | Returns a JSON array of transition records, ordered by time (newest first by default). Each record includes complete transition metadata, alert details, and timing information. |
| 2275 | |
| 2276 | **Performance Considerations:** |
| 2277 | - Use time ranges (after/before) to limit query scope |
| 2278 | - Use cardinality limits for large result sets |
| 2279 | - Timeout parameter prevents long-running queries |
| 2280 | - Pagination via anchor_gi for processing large datasets |
| 2281 | |
| 2282 | **Security & Access Control:** |
| 2283 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 2284 | - **Default Access:** Public (no authentication required) |
| 2285 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 2286 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 2287 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 2288 | security: |
| 2289 | - {} |
| 2290 | - bearerAuth: [] |
| 2291 | parameters: |
| 2292 | - name: scope_nodes |
| 2293 | in: query |
| 2294 | description: | |
| 2295 | Filter transitions to only include specific nodes using simple pattern matching. |
| 2296 | |
| 2297 | This parameter defines which nodes to include in the search using Netdata's simple pattern syntax (not regex). |
| 2298 | |
| 2299 | **Pattern Syntax:** |
| 2300 | - `*` matches any number of characters (including none) |
| 2301 | - `node1 node2` space-separated list matches any of the nodes |
| 2302 | - `!node3` exclude specific nodes (prefix with !) |
| 2303 | - Can combine inclusion and exclusion: `web* !web-test*` |
| 2304 | |
| 2305 | **Examples:** |
| 2306 | - `scope_nodes=web*` - All nodes starting with "web" |
| 2307 | - `scope_nodes=web* db*` - All web and database nodes |
| 2308 | - `scope_nodes=* !test*` - All nodes except test nodes |
| 2309 | - `scope_nodes=prod-web-01` - Specific node only |
| 2310 | |
| 2311 | **Use Cases:** |
| 2312 | - Focus on specific node groups (production vs staging) |
| 2313 | - Exclude test/development nodes from analysis |
| 2314 | - Investigate issues on specific infrastructure tiers |
| 2315 | |
| 2316 | When not specified, transitions from all nodes are included. |
| 2317 | required: false |
| 2318 | schema: |
| 2319 | type: string |
| 2320 | examples: |
| 2321 | all_web_nodes: |
| 2322 | value: "web*" |
| 2323 | summary: All web servers |
| 2324 | prod_only: |
| 2325 | value: "* !test* !dev*" |
| 2326 | summary: Production nodes only |
| 2327 | - name: nodes |
| 2328 | in: query |
| 2329 | description: | |
| 2330 | Filter transitions to specific nodes by their exact names. |
| 2331 | |
| 2332 | Unlike `scope_nodes` which supports patterns, this parameter requires exact node names. Multiple nodes are separated by comma or pipe. |
| 2333 | |
| 2334 | **Format:** Comma or pipe-separated list of exact node names |
| 2335 | |
| 2336 | **Examples:** |
| 2337 | - `nodes=web-server-01` - Single specific node |
| 2338 | - `nodes=web-server-01,web-server-02,db-server-01` - Multiple specific nodes |
| 2339 | - `nodes=web-server-01|web-server-02` - Pipe separator also works |
| 2340 | |
| 2341 | **Difference from scope_nodes:** |
| 2342 | - `scope_nodes`: Pattern matching, filters at query time |
| 2343 | - `nodes`: Exact names, more efficient for known node names |
| 2344 | |
| 2345 | **Best Practice:** Use `nodes` when you know exact node names, use `scope_nodes` for pattern-based filtering. |
| 2346 | |
| 2347 | When not specified, transitions from all nodes matching scope_nodes (or all nodes if scope_nodes is also not specified) are included. |
| 2348 | required: false |
| 2349 | schema: |
| 2350 | type: string |
| 2351 | example: "web-server-01,db-server-01" |
| 2352 | - name: scope_contexts |
| 2353 | in: query |
| 2354 | description: | |
| 2355 | Filter transitions to only include alerts from specific metric contexts using pattern matching. |
| 2356 | |
| 2357 | Contexts group similar metrics across instances (e.g., `system.cpu` groups CPU metrics from all nodes, `disk.io` groups disk I/O from all disks). |
| 2358 | |
| 2359 | **Pattern Syntax:** |
| 2360 | - `*` matches any number of characters |
| 2361 | - `context1 context2` space-separated list matches any of the contexts |
| 2362 | - `!context3` exclude specific contexts |
| 2363 | - Can combine: `system.* !system.io*` |
| 2364 | |
| 2365 | **Common Context Patterns:** |
| 2366 | - `system.*` - All system-level metrics |
| 2367 | - `disk.*` - All disk-related metrics |
| 2368 | - `net.*` - All network-related metrics |
| 2369 | - `mysql.*` - All MySQL metrics |
| 2370 | - `nginx.*` - All Nginx metrics |
| 2371 | |
| 2372 | **Examples:** |
| 2373 | - `scope_contexts=system.cpu` - Only CPU alerts |
| 2374 | - `scope_contexts=disk.* net.*` - All disk and network alerts |
| 2375 | - `scope_contexts=* !system.ip*` - All contexts except IP-related |
| 2376 | |
| 2377 | **Use Cases:** |
| 2378 | - Focus on specific subsystem (e.g., storage, network) |
| 2379 | - Exclude noisy alert types |
| 2380 | - Component-specific incident investigation |
| 2381 | |
| 2382 | When not specified, transitions from all contexts are included. |
| 2383 | required: false |
| 2384 | schema: |
| 2385 | type: string |
| 2386 | examples: |
| 2387 | disk_alerts: |
| 2388 | value: "disk.*" |
| 2389 | summary: All disk-related alerts |
| 2390 | critical_systems: |
| 2391 | value: "system.* disk.* net.*" |
| 2392 | summary: System, disk, and network alerts |
| 2393 | - name: contexts |
| 2394 | in: query |
| 2395 | description: | |
| 2396 | Filter transitions to specific contexts by their exact names. |
| 2397 | |
| 2398 | Unlike `scope_contexts` which supports patterns, this parameter requires exact context names. |
| 2399 | |
| 2400 | **Format:** Comma or pipe-separated list of exact context names |
| 2401 | |
| 2402 | **Examples:** |
| 2403 | - `contexts=system.cpu` - Single specific context |
| 2404 | - `contexts=system.cpu,system.load,system.ram` - Multiple contexts |
| 2405 | - `contexts=disk.space|disk.inodes` - Pipe separator |
| 2406 | |
| 2407 | **Difference from scope_contexts:** |
| 2408 | - `scope_contexts`: Pattern matching for flexible filtering |
| 2409 | - `contexts`: Exact names for precise filtering |
| 2410 | |
| 2411 | When not specified, transitions from all contexts matching scope_contexts are included. |
| 2412 | required: false |
| 2413 | schema: |
| 2414 | type: string |
| 2415 | example: "system.cpu,system.ram,disk.space" |
| 2416 | - name: alert |
| 2417 | in: query |
| 2418 | description: | |
| 2419 | Filter transitions to a specific alert by its exact name. |
| 2420 | |
| 2421 | Alert names are unique identifiers for specific alert configurations. |
| 2422 | |
| 2423 | **Format:** Exact alert name (case-sensitive) |
| 2424 | |
| 2425 | **Examples:** |
| 2426 | - `alert=disk_space_usage` - Transitions for disk space alert |
| 2427 | - `alert=cpu_usage` - Transitions for CPU usage alert |
| 2428 | - `alert=ram_in_use` - Transitions for RAM usage alert |
| 2429 | |
| 2430 | **Use Cases:** |
| 2431 | - Analyze history of a specific alert |
| 2432 | - Tune alert thresholds based on historical behavior |
| 2433 | - Investigate alert flapping (rapid state changes) |
| 2434 | - Track alert effectiveness |
| 2435 | |
| 2436 | **Tip:** To find available alert names, query `/api/v3/alerts` first or use the `/api/v3/alert_config` endpoint. |
| 2437 | |
| 2438 | When not specified, transitions for all alerts are included. |
| 2439 | required: false |
| 2440 | schema: |
| 2441 | type: string |
| 2442 | example: "disk_space_usage" |
| 2443 | - name: transition |
| 2444 | in: query |
| 2445 | description: | |
| 2446 | Filter to a specific transition by its unique identifier. |
| 2447 | |
| 2448 | Each transition has a unique ID (UUID). This parameter is rarely used but can retrieve exact transition records. |
| 2449 | |
| 2450 | **Format:** UUID string |
| 2451 | |
| 2452 | **Use Case:** Retrieve exact transition details when you have the transition ID from another query or notification. |
| 2453 | |
| 2454 | When not specified, all transitions matching other filters are included. |
| 2455 | required: false |
| 2456 | schema: |
| 2457 | type: string |
| 2458 | example: "550e8400-e29b-41d4-a716-446655440000" |
| 2459 | - name: last |
| 2460 | in: query |
| 2461 | description: | |
| 2462 | Limit the number of transition records returned. |
| 2463 | |
| 2464 | This controls how many transition records to include in the response, ordered by time (most recent first). |
| 2465 | |
| 2466 | **Format:** Positive integer |
| 2467 | |
| 2468 | **Default:** 1 (returns only the most recent transition) |
| 2469 | |
| 2470 | **Examples:** |
| 2471 | - `last=1` - Most recent transition only (default) |
| 2472 | - `last=100` - Last 100 transitions |
| 2473 | - `last=1000` - Last 1000 transitions |
| 2474 | |
| 2475 | **Use Cases:** |
| 2476 | - Dashboard widgets showing recent N alerts |
| 2477 | - API clients with pagination |
| 2478 | - Limiting response size for performance |
| 2479 | |
| 2480 | **Pagination:** |
| 2481 | For datasets larger than `last`, use the `anchor_gi` parameter to navigate to the next page: |
| 2482 | 1. Make request with `last=100` |
| 2483 | 2. Note the `global_id` of the last transition in response |
| 2484 | 3. Make next request with `last=100&anchor_gi=<global_id>` |
| 2485 | |
| 2486 | **Performance Note:** Smaller values of `last` result in faster queries and smaller responses. |
| 2487 | |
| 2488 | **IMPORTANT:** This parameter is required. If not specified, defaults to 1. |
| 2489 | required: true |
| 2490 | schema: |
| 2491 | type: integer |
| 2492 | minimum: 1 |
| 2493 | default: 1 |
| 2494 | example: 100 |
| 2495 | - name: anchor_gi |
| 2496 | in: query |
| 2497 | description: | |
| 2498 | Global ID anchor for pagination through large result sets. |
| 2499 | |
| 2500 | Each transition has a unique global_id (an incrementing number). Use this parameter to paginate through results by specifying the global_id of the last transition from the previous page. |
| 2501 | |
| 2502 | **How Pagination Works:** |
| 2503 | 1. First request: `?last=100` - Returns first 100 transitions |
| 2504 | 2. Extract `global_id` of the 100th (last) transition from response |
| 2505 | 3. Next request: `?last=100&anchor_gi=<global_id>` - Returns next 100 transitions |
| 2506 | |
| 2507 | **Format:** Positive integer (global_id from previous response) |
| 2508 | |
| 2509 | **Examples:** |
| 2510 | - `anchor_gi=12345` - Start from transition with global_id 12345 |
| 2511 | - Combined with last: `last=100&anchor_gi=12345` - Get 100 transitions starting after global_id 12345 |
| 2512 | |
| 2513 | **Use Cases:** |
| 2514 | - Processing large alert history datasets |
| 2515 | - Implementing "load more" in UIs |
| 2516 | - Batch processing of transition records |
| 2517 | - Exporting complete alert history |
| 2518 | |
| 2519 | **Direction:** |
| 2520 | - Results are ordered by global_id (which correlates with time) |
| 2521 | - Anchor specifies "start after this ID" |
| 2522 | - Each page contains `last` number of records |
| 2523 | |
| 2524 | When not specified, pagination starts from the most recent transition. |
| 2525 | required: false |
| 2526 | schema: |
| 2527 | type: integer |
| 2528 | format: int64 |
| 2529 | minimum: 0 |
| 2530 | example: 12345678 |
| 2531 | - name: f_status |
| 2532 | in: query |
| 2533 | description: | |
| 2534 | **Facet Filter:** Filter transitions by their NEW status (the status the alert transitioned TO). |
| 2535 | |
| 2536 | **Available Status Values:** |
| 2537 | - `CRITICAL` - Alert in critical state (highest severity) |
| 2538 | - `WARNING` - Alert in warning state |
| 2539 | - `CLEAR` - Alert returned to normal state |
| 2540 | - `UNDEFINED` - Alert evaluation failed (e.g., metric missing, division by zero) |
| 2541 | - `UNINITIALIZED` - Alert not yet evaluated (no data yet) |
| 2542 | - `REMOVED` - Alert was removed (plugin stopped, configuration changed) |
| 2543 | |
| 2544 | **Format:** Comma-separated list of status values |
| 2545 | |
| 2546 | **Examples:** |
| 2547 | - `f_status=CRITICAL` - Only transitions TO critical state |
| 2548 | - `f_status=CRITICAL,WARNING` - Transitions to critical or warning |
| 2549 | - `f_status=CLEAR` - When alerts cleared (returned to normal) |
| 2550 | |
| 2551 | **Use Cases:** |
| 2552 | - Find when alerts became critical: `f_status=CRITICAL` |
| 2553 | - Track alert recovery: `f_status=CLEAR` |
| 2554 | - Find alert failures: `f_status=UNDEFINED` |
| 2555 | - Incident timeline: `f_status=CRITICAL,WARNING` |
| 2556 | |
| 2557 | **Note:** This filters by the NEW status. To see transitions FROM a status to another, you'll need to examine the old_status field in the response. |
| 2558 | |
| 2559 | When not specified, transitions to all statuses are included. |
| 2560 | required: false |
| 2561 | schema: |
| 2562 | type: string |
| 2563 | examples: |
| 2564 | critical_only: |
| 2565 | value: "CRITICAL" |
| 2566 | summary: Only critical transitions |
| 2567 | problems: |
| 2568 | value: "CRITICAL,WARNING" |
| 2569 | summary: Problem states |
| 2570 | recoveries: |
| 2571 | value: "CLEAR" |
| 2572 | summary: Alert recoveries |
| 2573 | - name: f_type |
| 2574 | in: query |
| 2575 | description: | |
| 2576 | **Facet Filter:** Filter transitions by alert type. |
| 2577 | |
| 2578 | Alert types categorize alerts by what they monitor (e.g., "System", "Database", "Web Server"). |
| 2579 | |
| 2580 | **Format:** Comma-separated list of alert type names |
| 2581 | |
| 2582 | **Common Alert Types:** |
| 2583 | - `System` - System-level alerts (CPU, RAM, load) |
| 2584 | - `Database` - Database monitoring alerts |
| 2585 | - `Web Server` - Web server alerts (Nginx, Apache) |
| 2586 | - `Network` - Network-related alerts |
| 2587 | - `Storage` - Storage and disk alerts |
| 2588 | |
| 2589 | **Examples:** |
| 2590 | - `f_type=System` - Only system alerts |
| 2591 | - `f_type=Database,Web Server` - Database and web server alerts |
| 2592 | |
| 2593 | **Use Cases:** |
| 2594 | - Focus on specific infrastructure component types |
| 2595 | - Filter by technology stack (databases, web servers, etc.) |
| 2596 | - Team-specific alert filtering |
| 2597 | |
| 2598 | **Note:** The exact type values depend on your alert configurations. Query `/api/v3/alerts` to see available types in your installation. |
| 2599 | |
| 2600 | When not specified, transitions of all types are included. |
| 2601 | required: false |
| 2602 | schema: |
| 2603 | type: string |
| 2604 | example: "System,Database" |
| 2605 | - name: f_role |
| 2606 | in: query |
| 2607 | description: | |
| 2608 | **Facet Filter:** Filter transitions by recipient role. |
| 2609 | |
| 2610 | Roles define who should be notified about alerts (e.g., "sysadmin", "dba", "webmaster"). |
| 2611 | |
| 2612 | **Format:** Comma-separated list of role names |
| 2613 | |
| 2614 | **Common Roles:** |
| 2615 | - `sysadmin` - System administrators |
| 2616 | - `dba` - Database administrators |
| 2617 | - `webmaster` - Web server administrators |
| 2618 | - `devops` - DevOps team |
| 2619 | - `security` - Security team |
| 2620 | |
| 2621 | **Examples:** |
| 2622 | - `f_role=sysadmin` - Alerts for sysadmin role |
| 2623 | - `f_role=sysadmin,dba` - Alerts for sysadmins and DBAs |
| 2624 | |
| 2625 | **Use Cases:** |
| 2626 | - Team-specific alert filtering |
| 2627 | - Role-based alert analysis |
| 2628 | - Notification audit trails |
| 2629 | |
| 2630 | **Note:** Roles are defined in your alert configurations. The exact role values depend on your Netdata setup. |
| 2631 | |
| 2632 | When not specified, transitions for all roles are included. |
| 2633 | required: false |
| 2634 | schema: |
| 2635 | type: string |
| 2636 | example: "sysadmin,dba" |
| 2637 | - name: f_class |
| 2638 | in: query |
| 2639 | description: | |
| 2640 | **Facet Filter:** Filter transitions by alert classification. |
| 2641 | |
| 2642 | Alert classifications categorize alerts by their nature (e.g., "Errors", "Latency", "Utilization"). |
| 2643 | |
| 2644 | **Format:** Comma-separated list of classification names |
| 2645 | |
| 2646 | **Common Classifications:** |
| 2647 | - `Errors` - Error-related alerts |
| 2648 | - `Latency` - Performance/latency alerts |
| 2649 | - `Utilization` - Resource utilization alerts |
| 2650 | - `Availability` - Availability/uptime alerts |
| 2651 | - `Workload` - Workload-related alerts |
| 2652 | |
| 2653 | **Examples:** |
| 2654 | - `f_class=Errors` - Only error-related transitions |
| 2655 | - `f_class=Latency,Utilization` - Performance and utilization alerts |
| 2656 | |
| 2657 | **Use Cases:** |
| 2658 | - Focus on specific problem categories |
| 2659 | - SLA/SLO tracking by classification |
| 2660 | - Alert categorization analysis |
| 2661 | |
| 2662 | When not specified, transitions of all classifications are included. |
| 2663 | required: false |
| 2664 | schema: |
| 2665 | type: string |
| 2666 | example: "Errors,Latency" |
| 2667 | - name: f_component |
| 2668 | in: query |
| 2669 | description: | |
| 2670 | **Facet Filter:** Filter transitions by system component. |
| 2671 | |
| 2672 | Components identify which part of the system the alert relates to (e.g., "Network", "Disk", "Memory"). |
| 2673 | |
| 2674 | **Format:** Comma-separated list of component names |
| 2675 | |
| 2676 | **Common Components:** |
| 2677 | - `Network` - Network-related alerts |
| 2678 | - `Disk` - Disk/storage alerts |
| 2679 | - `Memory` - Memory alerts |
| 2680 | - `CPU` - CPU alerts |
| 2681 | - `Database` - Database component alerts |
| 2682 | |
| 2683 | **Examples:** |
| 2684 | - `f_component=Disk` - Only disk-related transitions |
| 2685 | - `f_component=Network,Disk` - Network and disk alerts |
| 2686 | |
| 2687 | **Use Cases:** |
| 2688 | - Component-specific incident investigation |
| 2689 | - Infrastructure subsystem analysis |
| 2690 | - Capacity planning by component |
| 2691 | |
| 2692 | When not specified, transitions for all components are included. |
| 2693 | required: false |
| 2694 | schema: |
| 2695 | type: string |
| 2696 | example: "Disk,Network" |
| 2697 | - name: f_node |
| 2698 | in: query |
| 2699 | description: | |
| 2700 | **Facet Filter:** Filter transitions by exact node hostname. |
| 2701 | |
| 2702 | This is a facet filter alternative to the `nodes` parameter, typically used when you want to combine it with other facets. |
| 2703 | |
| 2704 | **Format:** Comma-separated list of exact node hostnames |
| 2705 | |
| 2706 | **Examples:** |
| 2707 | - `f_node=web-server-01` - Single specific node |
| 2708 | - `f_node=web-server-01,db-server-01` - Multiple nodes |
| 2709 | |
| 2710 | **Difference from `nodes` parameter:** |
| 2711 | - Both accept exact node names |
| 2712 | - `f_node` is a facet filter (can be combined with other f_* filters) |
| 2713 | - `nodes` is a direct filter parameter |
| 2714 | |
| 2715 | **Best Practice:** Use `nodes` for simple node filtering, use `f_node` when combining with other facets in complex queries. |
| 2716 | |
| 2717 | When not specified, all nodes are included. |
| 2718 | required: false |
| 2719 | schema: |
| 2720 | type: string |
| 2721 | example: "web-server-01" |
| 2722 | - name: f_alert |
| 2723 | in: query |
| 2724 | description: | |
| 2725 | **Facet Filter:** Filter transitions by exact alert name. |
| 2726 | |
| 2727 | This is a facet filter alternative to the `alert` parameter. |
| 2728 | |
| 2729 | **Format:** Comma-separated list of exact alert names |
| 2730 | |
| 2731 | **Examples:** |
| 2732 | - `f_alert=disk_space_usage` - Single alert |
| 2733 | - `f_alert=cpu_usage,ram_in_use` - Multiple alerts |
| 2734 | |
| 2735 | **Difference from `alert` parameter:** |
| 2736 | - `alert`: Single alert name |
| 2737 | - `f_alert`: Multiple alert names, facet filter |
| 2738 | |
| 2739 | When not specified, all alerts are included. |
| 2740 | required: false |
| 2741 | schema: |
| 2742 | type: string |
| 2743 | example: "disk_space_usage,ram_in_use" |
| 2744 | - name: f_instance |
| 2745 | in: query |
| 2746 | description: | |
| 2747 | **Facet Filter:** Filter transitions by chart instance name. |
| 2748 | |
| 2749 | Chart instances are specific monitored entities (e.g., "disk_sda", "eth0", "mysql_localhost"). |
| 2750 | |
| 2751 | **Format:** Comma-separated list of instance names |
| 2752 | |
| 2753 | **Examples:** |
| 2754 | - `f_instance=sda` - Alerts for disk sda |
| 2755 | - `f_instance=eth0,eth1` - Alerts for network interfaces eth0 and eth1 |
| 2756 | |
| 2757 | **Use Cases:** |
| 2758 | - Device-specific alert history (specific disk, NIC, etc.) |
| 2759 | - Instance-level troubleshooting |
| 2760 | - Resource-specific analysis |
| 2761 | |
| 2762 | **Note:** Instance names depend on your system configuration and what's being monitored. |
| 2763 | |
| 2764 | When not specified, all instances are included. |
| 2765 | required: false |
| 2766 | schema: |
| 2767 | type: string |
| 2768 | example: "sda,sdb" |
| 2769 | - name: f_context |
| 2770 | in: query |
| 2771 | description: | |
| 2772 | **Facet Filter:** Filter transitions by exact metric context. |
| 2773 | |
| 2774 | This is a facet filter alternative to the `contexts` parameter. |
| 2775 | |
| 2776 | **Format:** Comma-separated list of exact context names |
| 2777 | |
| 2778 | **Examples:** |
| 2779 | - `f_context=system.cpu` - CPU context only |
| 2780 | - `f_context=disk.space,disk.inodes` - Disk space and inodes |
| 2781 | |
| 2782 | **Difference from `contexts` parameter:** |
| 2783 | - Both accept exact context names |
| 2784 | - `f_context` is a facet filter (can be combined with other f_* filters) |
| 2785 | - `contexts` is a direct filter parameter |
| 2786 | |
| 2787 | When not specified, all contexts are included. |
| 2788 | required: false |
| 2789 | schema: |
| 2790 | type: string |
| 2791 | example: "system.cpu,system.ram" |
| 2792 | - $ref: '#/components/parameters/after' |
| 2793 | - $ref: '#/components/parameters/before' |
| 2794 | - name: timeout |
| 2795 | in: query |
| 2796 | description: | |
| 2797 | Maximum time in milliseconds to wait for the query to complete. |
| 2798 | |
| 2799 | Alert transition queries can be expensive when searching large time ranges or across many nodes. |
| 2800 | |
| 2801 | **Format:** Integer (milliseconds) |
| 2802 | |
| 2803 | **Default:** Server default timeout (typically 30000ms = 30 seconds) |
| 2804 | |
| 2805 | **Examples:** |
| 2806 | - `timeout=5000` - 5 second timeout |
| 2807 | - `timeout=60000` - 60 second timeout (for large queries) |
| 2808 | |
| 2809 | **Use Cases:** |
| 2810 | - Prevent long-running queries from blocking |
| 2811 | - API clients with strict latency requirements |
| 2812 | - Dashboard widgets needing fast responses |
| 2813 | |
| 2814 | When timeout is exceeded, the server returns a partial result with whatever transitions were collected before timeout, or an error if no results were ready. |
| 2815 | required: false |
| 2816 | schema: |
| 2817 | type: integer |
| 2818 | format: int64 |
| 2819 | minimum: 1000 |
| 2820 | example: 30000 |
| 2821 | - name: cardinality |
| 2822 | in: query |
| 2823 | description: | |
| 2824 | Limit the number of transition records returned to prevent response explosion. |
| 2825 | |
| 2826 | **Format:** Integer (maximum number of transitions) |
| 2827 | |
| 2828 | **Default:** No limit (but respects `last` parameter) |
| 2829 | |
| 2830 | **Relationship with `last`:** |
| 2831 | - `last`: Controls result set size (pagination) |
| 2832 | - `cardinality`: Hard limit on response size |
| 2833 | |
| 2834 | **Use Cases:** |
| 2835 | - Ensure responses stay within size limits |
| 2836 | - Protect against accidentally requesting huge result sets |
| 2837 | - API clients with memory constraints |
| 2838 | |
| 2839 | **Example:** |
| 2840 | - `cardinality=1000` - Never return more than 1000 transitions |
| 2841 | |
| 2842 | **Alias:** Can also be specified as `cardinality_limit` |
| 2843 | |
| 2844 | **Best Practice:** Use `last` for normal pagination, use `cardinality` as a safety limit. |
| 2845 | |
| 2846 | When the limit is exceeded, the response may indicate how many transitions were omitted. |
| 2847 | required: false |
| 2848 | schema: |
| 2849 | type: integer |
| 2850 | minimum: 1 |
| 2851 | example: 1000 |
| 2852 | responses: |
| 2853 | "200": |
| 2854 | description: | |
| 2855 | Success. Returns alert transition history records. |
| 2856 | |
| 2857 | **Response Structure:** |
| 2858 | - Array of transition records, ordered by time (newest first by default) |
| 2859 | - Each record includes: |
| 2860 | - `global_id`: Unique transition ID for pagination |
| 2861 | - `transition_id`: UUID of this specific transition |
| 2862 | - `alert_name`: Name of the alert |
| 2863 | - `chart`, `chart_context`: What metric triggered the alert |
| 2864 | - `old_status`, `new_status`: Status change (e.g., WARNING → CRITICAL) |
| 2865 | - `old_value`, `new_value`: Metric values at transition |
| 2866 | - `when_key`: When the transition occurred (timestamp) |
| 2867 | - `duration`: How long the alert was in old_status |
| 2868 | - `non_clear_duration`: Time spent in non-CLEAR states |
| 2869 | - Alert metadata: type, classification, component, role, recipient |
| 2870 | - Execution details: exec, exec_code, exec_run_timestamp |
| 2871 | - Node information: machine_guid, hostname |
| 2872 | |
| 2873 | **Facets:** |
| 2874 | When not in MCP mode, the response includes facet information showing all available values for each facet filter (f_status, f_type, etc.) with counts. |
| 2875 | |
| 2876 | **Pagination:** |
| 2877 | - Use the `global_id` from the last record with `anchor_gi` parameter for next page |
| 2878 | - Response indicates if more results are available |
| 2879 | |
| 2880 | **Response Characteristics:** |
| 2881 | - JSON format |
| 2882 | - Not cacheable (new transitions constantly added) |
| 2883 | - May be cardinality-limited if specified |
| 2884 | - May be timeout-limited (partial results) |
| 2885 | |
| 2886 | **Example Usage:** |
| 2887 | ``` |
| 2888 | GET /api/v3/alert_transitions?last=100&f_status=CRITICAL&after=-86400 |
| 2889 | ``` |
| 2890 | Returns last 100 transitions to CRITICAL state in the past 24 hours. |
| 2891 | content: |
| 2892 | application/json: |
| 2893 | schema: |
| 2894 | type: object |
| 2895 | description: Alert transition history with pagination support |
| 2896 | "400": |
| 2897 | description: | |
| 2898 | Bad request. Common causes: |
| 2899 | - Invalid parameter values |
| 2900 | - Malformed filter patterns |
| 2901 | - Invalid facet values |
| 2902 | - Invalid timeout or cardinality values |
| 2903 | - Invalid global_id for anchor_gi |
| 2904 | "500": |
| 2905 | description: Internal server error during transition query execution. |
| 2906 | /api/v3/alert_config: |
| 2907 | get: |
| 2908 | operationId: alert_config_v3 |
| 2909 | tags: |
| 2910 | - alerts |
| 2911 | summary: Retrieve the configuration of a specific alert by its config hash ID |
| 2912 | description: | |
| 2913 | Returns the complete configuration of an alert identified by its unique configuration hash ID (UUID). This endpoint provides detailed information about how an alert is configured, including its thresholds, evaluation logic, notification settings, and metadata. |
| 2914 | |
| 2915 | **What is an Alert Configuration?** |
| 2916 | Each alert in Netdata has a unique configuration that defines: |
| 2917 | - Threshold values (warning and critical) |
| 2918 | - The metric expression being evaluated |
| 2919 | - Evaluation frequency and hysteresis |
| 2920 | - Who to notify (recipients and roles) |
| 2921 | - Notification settings and delays |
| 2922 | - Alert metadata (name, info, summary, classification) |
| 2923 | |
| 2924 | **Configuration Hash ID:** |
| 2925 | The `config` parameter is a UUID that uniquely identifies an alert configuration. Multiple alert instances may share the same configuration hash if they use identical alert rules. |
| 2926 | |
| 2927 | **How to Get Config Hash IDs:** |
| 2928 | - From `/api/v3/alerts` response - each alert includes its `config_hash_id` |
| 2929 | - From `/api/v3/alert_transitions` response - transitions include `config_hash_id` |
| 2930 | - From alert notifications - config hash is often included in alert payloads |
| 2931 | |
| 2932 | **Use Cases:** |
| 2933 | - **Alert Investigation:** Understand exactly what thresholds triggered an alert |
| 2934 | - **Alert Tuning:** Review current configuration before making changes |
| 2935 | - **Documentation:** Generate documentation of alert configurations |
| 2936 | - **Audit Trails:** Track what alert configurations were in effect at specific times |
| 2937 | - **Troubleshooting:** Verify alert logic when investigating false positives/negatives |
| 2938 | - **Configuration Management:** Compare configurations across environments |
| 2939 | |
| 2940 | **Response Content:** |
| 2941 | The endpoint returns the complete alert configuration in the format it was defined (typically the Netdata health configuration syntax), including: |
| 2942 | - Alert name and type |
| 2943 | - The metric expression (`on` clause) |
| 2944 | - Warning and critical threshold expressions |
| 2945 | - Calculation method and dimensions |
| 2946 | - Lookup parameters (duration, method) |
| 2947 | - Notification recipients and roles |
| 2948 | - Alert metadata (info, summary, classification, component) |
| 2949 | - Delay settings and hysteresis rules |
| 2950 | |
| 2951 | **Example Workflow:** |
| 2952 | 1. Query alerts: `GET /api/v3/alerts?alert=disk_space_usage` |
| 2953 | 2. Extract `config_hash_id` from response |
| 2954 | 3. Get config: `GET /api/v3/alert_config?config=<uuid>` |
| 2955 | 4. Review/analyze the alert configuration details |
| 2956 | |
| 2957 | **Note:** This endpoint requires the exact config hash UUID. Invalid or non-existent UUIDs will return a 400 Bad Request error. |
| 2958 | |
| 2959 | **Security & Access Control:** |
| 2960 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 2961 | - **Default Access:** Public (no authentication required) |
| 2962 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 2963 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 2964 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 2965 | security: |
| 2966 | - {} |
| 2967 | - bearerAuth: [] |
| 2968 | parameters: |
| 2969 | - name: config |
| 2970 | in: query |
| 2971 | description: | |
| 2972 | The unique configuration hash ID (UUID) of the alert whose configuration to retrieve. |
| 2973 | |
| 2974 | **Format:** UUID string (with or without hyphens) |
| 2975 | |
| 2976 | **Where to Find Config Hash IDs:** |
| 2977 | 1. **From /api/v3/alerts Response:** |
| 2978 | Each alert in the response includes a `config_hash_id` field containing the UUID |
| 2979 | |
| 2980 | 2. **From /api/v3/alert_transitions Response:** |
| 2981 | Transition records include `config_hash_id` showing which config was active |
| 2982 | |
| 2983 | 3. **From Alert Notifications:** |
| 2984 | Alert notifications (email, Slack, etc.) often include the config hash |
| 2985 | |
| 2986 | 4. **From Logs:** |
| 2987 | Netdata logs may reference config hashes when loading alert configurations |
| 2988 | |
| 2989 | **UUID Format Examples:** |
| 2990 | - With hyphens: `550e8400-e29b-41d4-a716-446655440000` |
| 2991 | - Without hyphens: `550e8400e29b41d4a716446655440000` |
| 2992 | - Both formats are accepted |
| 2993 | |
| 2994 | **Important Notes:** |
| 2995 | - This parameter is **REQUIRED** |
| 2996 | - Must be a valid UUID format |
| 2997 | - Must reference an existing alert configuration |
| 2998 | - Case-insensitive |
| 2999 | |
| 3000 | **Common Errors:** |
| 3001 | - Missing config parameter → 400 Bad Request with message "A config hash ID is required" |
| 3002 | - Invalid UUID format → 400 Bad Request |
| 3003 | - Non-existent UUID → 404 or empty result |
| 3004 | |
| 3005 | **Example Usage:** |
| 3006 | ``` |
| 3007 | GET /api/v3/alert_config?config=550e8400-e29b-41d4-a716-446655440000 |
| 3008 | ``` |
| 3009 | |
| 3010 | **Tip:** To find all config hash IDs for a specific alert name, query the alerts endpoint first: |
| 3011 | ``` |
| 3012 | GET /api/v3/alerts?alert=disk_space_usage |
| 3013 | ``` |
| 3014 | Then extract the `config_hash_id` from the response. |
| 3015 | required: true |
| 3016 | schema: |
| 3017 | type: string |
| 3018 | format: uuid |
| 3019 | example: "550e8400-e29b-41d4-a716-446655440000" |
| 3020 | responses: |
| 3021 | "200": |
| 3022 | description: | |
| 3023 | Success. Returns the complete alert configuration. |
| 3024 | |
| 3025 | **Response Format:** |
| 3026 | The response contains the alert configuration in a structured format, typically including: |
| 3027 | |
| 3028 | **Core Configuration:** |
| 3029 | - `name`: Alert name/identifier |
| 3030 | - `type`: Alert classification type |
| 3031 | - `on`: Metric expression being monitored |
| 3032 | - `class`: Alert classification category |
| 3033 | - `component`: System component being monitored |
| 3034 | - `lookup`: Metric lookup parameters (method, duration, dimensions) |
| 3035 | |
| 3036 | **Thresholds:** |
| 3037 | - `warn`: Warning threshold expression |
| 3038 | - `crit`: Critical threshold expression |
| 3039 | - `units`: Unit of measurement for values |
| 3040 | |
| 3041 | **Evaluation:** |
| 3042 | - `every`: How often the alert is evaluated |
| 3043 | - `green` / `red`: Hysteresis settings (when to clear/trigger) |
| 3044 | - `calc`: Calculation expression (if any) |
| 3045 | |
| 3046 | **Notifications:** |
| 3047 | - `to`: Notification recipients |
| 3048 | - `exec`: Script to execute on alert |
| 3049 | - `delay`: Notification delay settings |
| 3050 | - `repeat`: Repeat notification settings |
| 3051 | |
| 3052 | **Metadata:** |
| 3053 | - `info`: Detailed alert description |
| 3054 | - `summary`: Brief alert summary |
| 3055 | - `host_labels`: Labels for host filtering |
| 3056 | |
| 3057 | **Response Characteristics:** |
| 3058 | - Content-Type: Typically `text/plain` or `application/json` depending on format |
| 3059 | - Not cacheable (configurations may change) |
| 3060 | - Complete configuration as it exists in the system |
| 3061 | |
| 3062 | **Example Response Structure (JSON format):** |
| 3063 | ```json |
| 3064 | { |
| 3065 | "name": "disk_space_usage", |
| 3066 | "on": "disk.space", |
| 3067 | "class": "Utilization", |
| 3068 | "type": "System", |
| 3069 | "component": "Disk", |
| 3070 | "lookup": "average -1m percentage of used", |
| 3071 | "units": "%", |
| 3072 | "warn": "$this > 80", |
| 3073 | "crit": "$this > 95", |
| 3074 | "info": "Disk space utilization is high", |
| 3075 | "to": "sysadmin" |
| 3076 | } |
| 3077 | ``` |
| 3078 | |
| 3079 | The exact format and fields depend on the alert configuration and may vary between different alert types. |
| 3080 | content: |
| 3081 | application/json: |
| 3082 | schema: |
| 3083 | type: object |
| 3084 | description: Alert configuration details |
| 3085 | text/plain: |
| 3086 | schema: |
| 3087 | type: string |
| 3088 | description: Alert configuration in text format |
| 3089 | "400": |
| 3090 | description: | |
| 3091 | Bad request. Common causes: |
| 3092 | - Missing `config` parameter (error: "A config hash ID is required. Add ?config=UUID query param") |
| 3093 | - Invalid UUID format |
| 3094 | - Malformed request |
| 3095 | |
| 3096 | **Error Response:** |
| 3097 | Returns plain text error message explaining what went wrong. |
| 3098 | "404": |
| 3099 | description: | |
| 3100 | Configuration not found. The specified config hash ID does not exist or has been removed. |
| 3101 | |
| 3102 | **Common Reasons:** |
| 3103 | - Alert configuration was deleted |
| 3104 | - Alert configuration was modified (gets a new hash) |
| 3105 | - UUID was mistyped |
| 3106 | - Configuration is from a different Netdata instance |
| 3107 | "500": |
| 3108 | description: Internal server error during configuration retrieval. |
| 3109 | /api/v3/variable: |
| 3110 | get: |
| 3111 | operationId: variable_v3 |
| 3112 | tags: |
| 3113 | - variables |
| 3114 | summary: Retrieve the value of a specific chart variable used in alert expressions |
| 3115 | description: | |
| 3116 | 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. |
| 3117 | |
| 3118 | **What are Chart Variables?** |
| 3119 | Variables in Netdata are named values that can be: |
| 3120 | - **Chart-specific metrics:** Current values from dimensions (e.g., `$used`, `$total`) |
| 3121 | - **Calculated values:** Derived from chart data (e.g., percentages, ratios) |
| 3122 | - **Statistical values:** Min, max, average values over time windows |
| 3123 | - **Alert-related values:** Previous alert states, thresholds |
| 3124 | - **System variables:** Host labels, node information |
| 3125 | |
| 3126 | **Common Use Cases:** |
| 3127 | - **Alert Threshold Debugging:** Understand what value triggered an alert |
| 3128 | - **Alert Expression Development:** Test variable values while writing alert expressions |
| 3129 | - **Troubleshooting:** Verify variable calculations are correct |
| 3130 | - **Dynamic Configuration:** Check runtime values used in alert logic |
| 3131 | |
| 3132 | **Variable Types:** |
| 3133 | 1. **Dimension Variables:** Direct dimension values (e.g., `used`, `free`, `cached`) |
| 3134 | 2. **Lookup Variables:** Result of lookup operations over time ranges |
| 3135 | 3. **Calculated Variables:** Custom calculations defined in alert configs |
| 3136 | 4. **Chart Variables:** Chart-level metadata (family, units, etc.) |
| 3137 | 5. **Host Variables:** Host-specific values and labels |
| 3138 | |
| 3139 | **Example Variables:** |
| 3140 | - `$this` - The current calculated value |
| 3141 | - `$used` - Value of "used" dimension |
| 3142 | - `$total` - Value of "total" dimension |
| 3143 | - `$1hour_cpu_usage` - CPU usage over last hour (lookup variable) |
| 3144 | - `$ram_percentage` - Calculated RAM usage percentage |
| 3145 | |
| 3146 | **How Variables Work in Alerts:** |
| 3147 | Alert expressions like `$this > 80` use variables to dynamically evaluate conditions. This endpoint lets you see the actual runtime values of these variables. |
| 3148 | |
| 3149 | **Workflow for Alert Development:** |
| 3150 | 1. Identify the chart: `GET /api/v1/charts` or `GET /api/v3/contexts` |
| 3151 | 2. Get variable value: `GET /api/v3/variable?chart=system.ram&variable=$used` |
| 3152 | 3. Test alert expression with actual values |
| 3153 | 4. Refine alert thresholds based on variable behavior |
| 3154 | |
| 3155 | **Response Format:** |
| 3156 | Returns JSON with the variable value and metadata about how it was calculated, including: |
| 3157 | - Current value |
| 3158 | - Calculation trace (how the value was computed) |
| 3159 | - Source dimensions |
| 3160 | - Any transformations applied |
| 3161 | |
| 3162 | **Note:** This is a specialized endpoint primarily used for alert development and troubleshooting. For general metric values, use `/api/v3/data` instead. |
| 3163 | |
| 3164 | **Security & Access Control:** |
| 3165 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 3166 | - **Default Access:** Public (no authentication required) |
| 3167 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 3168 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 3169 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 3170 | security: |
| 3171 | - {} |
| 3172 | - bearerAuth: [] |
| 3173 | parameters: |
| 3174 | - name: chart |
| 3175 | in: query |
| 3176 | description: | |
| 3177 | The chart identifier (ID or name) where the variable is defined. |
| 3178 | |
| 3179 | **Chart Identifier Format:** |
| 3180 | Charts can be specified by either their unique ID or their name. |
| 3181 | |
| 3182 | **Chart ID Format:** |
| 3183 | - Format: `type.name` (e.g., `system.cpu`, `disk.sda_io`, `mysql.queries`) |
| 3184 | - This is the canonical identifier shown in chart metadata |
| 3185 | - Case-sensitive |
| 3186 | - More reliable as it doesn't change |
| 3187 | |
| 3188 | **Chart Name Format:** |
| 3189 | - Human-readable name (e.g., "System CPU") |
| 3190 | - May contain spaces |
| 3191 | - Less reliable as it can change |
| 3192 | - The API will try to find by name if ID lookup fails |
| 3193 | |
| 3194 | **How to Find Chart IDs:** |
| 3195 | 1. **From /api/v1/charts:** |
| 3196 | ``` |
| 3197 | GET /api/v1/charts |
| 3198 | ``` |
| 3199 | Response includes all chart IDs in the system |
| 3200 | |
| 3201 | 2. **From /api/v3/contexts:** |
| 3202 | ``` |
| 3203 | GET /api/v3/contexts |
| 3204 | ``` |
| 3205 | Lists contexts and their chart instances |
| 3206 | |
| 3207 | 3. **From Alert Configuration:** |
| 3208 | Alert configs reference charts in their `on` clause |
| 3209 | |
| 3210 | 4. **From Netdata Dashboard:** |
| 3211 | Chart IDs are shown in chart metadata |
| 3212 | |
| 3213 | **Examples:** |
| 3214 | - `chart=system.cpu` - System CPU chart |
| 3215 | - `chart=system.ram` - System RAM chart |
| 3216 | - `chart=disk.sda_io` - Disk sda I/O chart |
| 3217 | - `chart=mysql.queries` - MySQL queries chart |
| 3218 | |
| 3219 | **Common Chart IDs by Category:** |
| 3220 | - **System:** `system.cpu`, `system.load`, `system.ram`, `system.io` |
| 3221 | - **Disk:** `disk.space`, `disk.io`, `disk.inodes` |
| 3222 | - **Network:** `net.eth0`, `net.packets` |
| 3223 | - **Databases:** `mysql.queries`, `postgres.connections`, `redis.memory` |
| 3224 | |
| 3225 | **Important Notes:** |
| 3226 | - This parameter is **REQUIRED** |
| 3227 | - Must reference an existing chart on the specified host |
| 3228 | - Chart must be actively collecting data |
| 3229 | - Case-sensitive |
| 3230 | |
| 3231 | **Error Handling:** |
| 3232 | - Missing parameter → 400 Bad Request: "A chart= and a variable= are required." |
| 3233 | - Invalid/non-existent chart → 404 Not Found: "Chart is not found: <chart>" |
| 3234 | required: true |
| 3235 | schema: |
| 3236 | type: string |
| 3237 | examples: |
| 3238 | system_ram: |
| 3239 | value: "system.ram" |
| 3240 | summary: System RAM chart |
| 3241 | disk_space: |
| 3242 | value: "disk.space" |
| 3243 | summary: Disk space chart |
| 3244 | mysql: |
| 3245 | value: "mysql.queries" |
| 3246 | summary: MySQL queries chart |
| 3247 | - name: variable |
| 3248 | in: query |
| 3249 | description: | |
| 3250 | The variable name to look up within the specified chart. |
| 3251 | |
| 3252 | **Variable Name Format:** |
| 3253 | Variable names typically follow these conventions: |
| 3254 | - Start with `$` in alert expressions, but the `$` is optional in this parameter |
| 3255 | - Names are case-sensitive |
| 3256 | - Can reference dimensions, calculated values, or lookups |
| 3257 | |
| 3258 | **Variable Name Categories:** |
| 3259 | |
| 3260 | **1. Dimension Variables (most common):** |
| 3261 | Direct references to chart dimensions: |
| 3262 | - `used` - Value of "used" dimension |
| 3263 | - `free` - Value of "free" dimension |
| 3264 | - `cached` - Value of "cached" dimension |
| 3265 | - `buffers` - Value of "buffers" dimension |
| 3266 | - `read` - Read operations/bytes |
| 3267 | - `write` - Write operations/bytes |
| 3268 | |
| 3269 | **2. Special Variables:** |
| 3270 | - `this` - The calculated/evaluated value from alert expression |
| 3271 | - `status` - Current alert status |
| 3272 | - `value` - Current metric value |
| 3273 | |
| 3274 | **3. Lookup Variables:** |
| 3275 | Variables created via lookup operations: |
| 3276 | - Format: `<duration>_<dimension>_<method>` |
| 3277 | - Example: `1hour_cpu_avg` - Average CPU over last hour |
| 3278 | - Example: `5min_disk_used_max` - Max disk used in last 5 minutes |
| 3279 | |
| 3280 | **4. Calculated Variables:** |
| 3281 | Custom variables defined in alert configurations: |
| 3282 | - `ram_percentage` - (used / total) * 100 |
| 3283 | - `disk_usage_ratio` - used / total |
| 3284 | - `error_rate` - errors / total_requests |
| 3285 | |
| 3286 | **5. Chart Metadata Variables:** |
| 3287 | - `family` - Chart family/category |
| 3288 | - `units` - Chart units |
| 3289 | - `chart_type` - Chart type |
| 3290 | |
| 3291 | **How to Discover Available Variables:** |
| 3292 | 1. **From Alert Configuration:** |
| 3293 | Alert expressions reveal which variables are available |
| 3294 | ``` |
| 3295 | GET /api/v3/alert_config?config=<uuid> |
| 3296 | ``` |
| 3297 | |
| 3298 | 2. **From /api/v1/alarm_variables:** |
| 3299 | Lists all variables for a chart |
| 3300 | ``` |
| 3301 | GET /api/v1/alarm_variables?chart=system.ram |
| 3302 | ``` |
| 3303 | |
| 3304 | 3. **From Chart Dimensions:** |
| 3305 | Dimension names are typically available as variables |
| 3306 | ``` |
| 3307 | GET /api/v1/chart?chart=system.ram |
| 3308 | ``` |
| 3309 | |
| 3310 | **Common Variable Examples by Chart:** |
| 3311 | |
| 3312 | **For system.ram:** |
| 3313 | - `used`, `free`, `cached`, `buffers` |
| 3314 | |
| 3315 | **For system.cpu:** |
| 3316 | - `user`, `system`, `nice`, `idle`, `iowait` |
| 3317 | |
| 3318 | **For disk.space:** |
| 3319 | - `used`, `avail` (available), `reserved` |
| 3320 | |
| 3321 | **For disk.io:** |
| 3322 | - `read`, `write` |
| 3323 | |
| 3324 | **For mysql.queries:** |
| 3325 | - `select`, `insert`, `update`, `delete` |
| 3326 | |
| 3327 | **Important Notes:** |
| 3328 | - This parameter is **REQUIRED** |
| 3329 | - Variable name must exist in the chart's variable set |
| 3330 | - Case-sensitive |
| 3331 | - The `$` prefix is optional (both `$used` and `used` work) |
| 3332 | |
| 3333 | **Error Handling:** |
| 3334 | - Missing parameter → 400 Bad Request: "A chart= and a variable= are required." |
| 3335 | - Non-existent variable → Returns trace showing variable not found |
| 3336 | required: true |
| 3337 | schema: |
| 3338 | type: string |
| 3339 | examples: |
| 3340 | dimension_value: |
| 3341 | value: "used" |
| 3342 | summary: Get 'used' dimension value |
| 3343 | with_dollar: |
| 3344 | value: "$used" |
| 3345 | summary: Variable with $ prefix (equivalent) |
| 3346 | special_variable: |
| 3347 | value: "this" |
| 3348 | summary: Current calculated value |
| 3349 | responses: |
| 3350 | "200": |
| 3351 | description: | |
| 3352 | Success. Returns the variable value and calculation trace. |
| 3353 | |
| 3354 | **Response Structure:** |
| 3355 | The response is a JSON object containing: |
| 3356 | |
| 3357 | **Variable Lookup Trace:** |
| 3358 | Shows the step-by-step process of how the variable value was calculated: |
| 3359 | - Variable name being looked up |
| 3360 | - Source dimensions queried |
| 3361 | - Calculation methods applied |
| 3362 | - Intermediate values |
| 3363 | - Final calculated value |
| 3364 | |
| 3365 | **Example Response:** |
| 3366 | ```json |
| 3367 | { |
| 3368 | "variable": "$used", |
| 3369 | "chart": "system.ram", |
| 3370 | "value": 8589934592, |
| 3371 | "units": "B", |
| 3372 | "trace": [ |
| 3373 | { |
| 3374 | "step": "lookup_dimension", |
| 3375 | "dimension": "used", |
| 3376 | "raw_value": 8589934592 |
| 3377 | }, |
| 3378 | { |
| 3379 | "step": "final_value", |
| 3380 | "value": 8589934592, |
| 3381 | "units": "B" |
| 3382 | } |
| 3383 | ] |
| 3384 | } |
| 3385 | ``` |
| 3386 | |
| 3387 | **Response Fields:** |
| 3388 | - `variable`: The requested variable name |
| 3389 | - `chart`: The chart ID where variable was found |
| 3390 | - `value`: Current numeric value of the variable |
| 3391 | - `units`: Unit of measurement |
| 3392 | - `trace`: Array of calculation steps showing how value was derived |
| 3393 | |
| 3394 | **Trace Information:** |
| 3395 | The trace provides transparency into variable evaluation, showing: |
| 3396 | - Dimension lookups performed |
| 3397 | - Data aggregation methods used |
| 3398 | - Time ranges evaluated |
| 3399 | - Transformations applied |
| 3400 | - Why certain values were selected |
| 3401 | |
| 3402 | **Use Cases for Trace:** |
| 3403 | - **Debugging Alerts:** Understand why an alert triggered |
| 3404 | - **Validating Logic:** Verify alert expressions evaluate correctly |
| 3405 | - **Performance Analysis:** See which dimensions contribute to variable |
| 3406 | - **Education:** Learn how alert variables are calculated |
| 3407 | |
| 3408 | **Response Characteristics:** |
| 3409 | - Content-Type: application/json |
| 3410 | - Not cacheable (values change constantly) |
| 3411 | - Real-time evaluation at query time |
| 3412 | - Includes calculation metadata |
| 3413 | |
| 3414 | **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. |
| 3415 | content: |
| 3416 | application/json: |
| 3417 | schema: |
| 3418 | type: object |
| 3419 | description: Variable value and calculation trace |
| 3420 | "400": |
| 3421 | description: | |
| 3422 | Bad request. Common causes: |
| 3423 | - Missing `chart` parameter (error: "A chart= and a variable= are required.") |
| 3424 | - Missing `variable` parameter (error: "A chart= and a variable= are required.") |
| 3425 | - Empty parameter values |
| 3426 | - Malformed request |
| 3427 | |
| 3428 | **Error Response:** |
| 3429 | Returns plain text error message explaining what went wrong. |
| 3430 | |
| 3431 | **Example Error:** |
| 3432 | ``` |
| 3433 | A chart= and a variable= are required. |
| 3434 | ``` |
| 3435 | "404": |
| 3436 | description: | |
| 3437 | Chart not found. The specified chart ID or name does not exist. |
| 3438 | |
| 3439 | **Error Response:** |
| 3440 | Returns plain text message indicating chart was not found. |
| 3441 | |
| 3442 | **Example Error:** |
| 3443 | ``` |
| 3444 | Chart is not found: system.nonexistent |
| 3445 | ``` |
| 3446 | |
| 3447 | **Common Reasons:** |
| 3448 | - Chart ID was mistyped |
| 3449 | - Chart doesn't exist on this host |
| 3450 | - Chart was removed (plugin stopped collecting) |
| 3451 | - Chart is on a different node (check node parameter if in multi-node setup) |
| 3452 | |
| 3453 | **Troubleshooting:** |
| 3454 | 1. List available charts: `GET /api/v1/charts` |
| 3455 | 2. Verify chart ID spelling and capitalization |
| 3456 | 3. Check if chart is actively collecting data |
| 3457 | 4. Ensure you're querying the correct node |
| 3458 | "500": |
| 3459 | description: Internal server error during variable lookup. |
| 3460 | /api/v3/info: |
| 3461 | get: |
| 3462 | operationId: info_v3 |
| 3463 | tags: |
| 3464 | - nodes |
| 3465 | summary: Retrieve detailed Netdata agent information across all nodes |
| 3466 | description: | |
| 3467 | 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. |
| 3468 | |
| 3469 | **What is Netdata Agent Information?** |
| 3470 | The `info` endpoint provides detailed metadata about the Netdata monitoring agent itself, including: |
| 3471 | - Agent version and build information |
| 3472 | - System capabilities and features enabled |
| 3473 | - Collection status and health |
| 3474 | - Host configuration and labels |
| 3475 | - Database information (storage, retention) |
| 3476 | - Plugin and collector status |
| 3477 | - Operating system details |
| 3478 | - Hardware information |
| 3479 | |
| 3480 | **Difference from /api/v3/nodes:** |
| 3481 | - **`/api/v3/nodes`:** Returns lightweight node list with basic identification |
| 3482 | - **`/api/v3/info`:** Returns comprehensive agent details with full capabilities and configuration |
| 3483 | |
| 3484 | **Multi-Node Support:** |
| 3485 | When queried on a Netdata Parent, this endpoint can return information for: |
| 3486 | - The parent agent itself |
| 3487 | - All child agents (streaming to the parent) |
| 3488 | - Filtered subsets using scope_nodes/nodes parameters |
| 3489 | |
| 3490 | **Use Cases:** |
| 3491 | - **Infrastructure Inventory:** Complete catalog of all Netdata installations |
| 3492 | - **Version Audits:** Find agents that need updates |
| 3493 | - **Capability Discovery:** What features are available on each node |
| 3494 | - **Health Monitoring:** Verify agent collection status |
| 3495 | - **Configuration Management:** Understand how agents are configured |
| 3496 | - **Troubleshooting:** Diagnose agent-specific issues |
| 3497 | - **License/Compliance:** Track Netdata deployments |
| 3498 | |
| 3499 | **Information Categories:** |
| 3500 | |
| 3501 | **1. Agent Identity:** |
| 3502 | - Unique agent ID (machine_guid) |
| 3503 | - Hostname |
| 3504 | - Agent version and commit |
| 3505 | - Build information |
| 3506 | |
| 3507 | **2. System Information:** |
| 3508 | - Operating system and kernel |
| 3509 | - CPU architecture |
| 3510 | - Virtualization platform |
| 3511 | - Container runtime (if applicable) |
| 3512 | |
| 3513 | **3. Database & Storage:** |
| 3514 | - Database mode (dbengine, ram, alloc) |
| 3515 | - Retention period |
| 3516 | - Storage capacity |
| 3517 | - Disk space usage |
| 3518 | |
| 3519 | **4. Features & Capabilities:** |
| 3520 | - ML/anomaly detection status |
| 3521 | - ACLK (cloud connection) status |
| 3522 | - Streaming capabilities |
| 3523 | - Available collectors |
| 3524 | |
| 3525 | **5. Collection Status:** |
| 3526 | - Number of charts collecting |
| 3527 | - Number of dimensions |
| 3528 | - Collection frequency |
| 3529 | - Last collection timestamp |
| 3530 | |
| 3531 | **6. Host Labels:** |
| 3532 | - Custom labels assigned to the host |
| 3533 | - Automatic labels (OS, architecture, etc.) |
| 3534 | - Cloud provider information (if detected) |
| 3535 | |
| 3536 | **Performance Characteristics:** |
| 3537 | - Fast query (primarily metadata lookups) |
| 3538 | - No time-series data processing |
| 3539 | - Results can be cached for reasonable duration |
| 3540 | - Supports filtering by node patterns |
| 3541 | |
| 3542 | **Example Usage:** |
| 3543 | ``` |
| 3544 | # Get info for all nodes |
| 3545 | GET /api/v3/info |
| 3546 | |
| 3547 | # Get info for specific nodes |
| 3548 | GET /api/v3/info?nodes=web-server-01,db-server-01 |
| 3549 | |
| 3550 | # Get info for nodes matching pattern |
| 3551 | GET /api/v3/info?scope_nodes=prod-* |
| 3552 | |
| 3553 | # Include specific options |
| 3554 | GET /api/v3/info?options=full |
| 3555 | ``` |
| 3556 | |
| 3557 | **Response Format:** |
| 3558 | Returns JSON with agent information grouped by node, including complete details about each agent's capabilities, configuration, and current status. |
| 3559 | |
| 3560 | **Security & Access Control:** |
| 3561 | - 🔓 **Always Public API** - This endpoint is always accessible without authentication |
| 3562 | - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions |
| 3563 | - **No Authentication:** Cannot be restricted by any configuration |
| 3564 | - **Access:** Available to anyone who can reach the agent's HTTP endpoint |
| 3565 | parameters: |
| 3566 | - name: scope_nodes |
| 3567 | in: query |
| 3568 | description: | |
| 3569 | Filter to specific nodes using simple pattern matching. |
| 3570 | |
| 3571 | **Pattern Syntax:** |
| 3572 | - `*` matches any characters |
| 3573 | - Space-separated list for multiple patterns |
| 3574 | - `!` prefix to exclude |
| 3575 | - Combine with: `web* !web-test*` |
| 3576 | |
| 3577 | **Examples:** |
| 3578 | - `scope_nodes=web*` - All web servers |
| 3579 | - `scope_nodes=prod-*` - All production nodes |
| 3580 | - `scope_nodes=* !test*` - All except test nodes |
| 3581 | |
| 3582 | **Use Cases:** |
| 3583 | - Focus on specific infrastructure tiers |
| 3584 | - Exclude development/test environments |
| 3585 | - Group by naming conventions |
| 3586 | |
| 3587 | When not specified, returns info for all nodes. |
| 3588 | required: false |
| 3589 | schema: |
| 3590 | type: string |
| 3591 | example: "prod-*" |
| 3592 | - name: nodes |
| 3593 | in: query |
| 3594 | description: | |
| 3595 | Filter to specific nodes by exact names. |
| 3596 | |
| 3597 | Unlike `scope_nodes`, this requires exact node names (no patterns). |
| 3598 | |
| 3599 | **Format:** Comma or pipe-separated list |
| 3600 | |
| 3601 | **Examples:** |
| 3602 | - `nodes=web-server-01` - Single node |
| 3603 | - `nodes=web-server-01,db-server-01` - Multiple nodes |
| 3604 | - `nodes=web-01|web-02` - Pipe separator |
| 3605 | |
| 3606 | **Best Practice:** |
| 3607 | - Use `nodes` when you know exact names |
| 3608 | - Use `scope_nodes` for pattern-based filtering |
| 3609 | |
| 3610 | When not specified, returns info for all nodes matching scope_nodes. |
| 3611 | required: false |
| 3612 | schema: |
| 3613 | type: string |
| 3614 | example: "web-server-01,db-server-01" |
| 3615 | - name: options |
| 3616 | in: query |
| 3617 | description: | |
| 3618 | Control the level of detail and what information to include in the response. |
| 3619 | |
| 3620 | **Available Options:** |
| 3621 | - `full` or `all` - Include all available information |
| 3622 | - `labels` - Include host labels |
| 3623 | - `uuids` - Include UUIDs and identifiers |
| 3624 | - `deleted` - Include information about deleted/offline nodes |
| 3625 | - `hidden` - Include hidden agents |
| 3626 | |
| 3627 | **Examples:** |
| 3628 | - `options=full` - Complete information |
| 3629 | - `options=labels,uuids` - Labels and identifiers |
| 3630 | - `options=labels|uuids` - Pipe separator also works |
| 3631 | |
| 3632 | **Default Behavior:** |
| 3633 | When not specified, returns standard information without deleted/hidden nodes and without excessive detail. |
| 3634 | |
| 3635 | **Use Cases:** |
| 3636 | - Inventory systems need `full` detail |
| 3637 | - Label-based filtering needs `labels` |
| 3638 | - Historical analysis may need `deleted` |
| 3639 | required: false |
| 3640 | schema: |
| 3641 | type: string |
| 3642 | example: "full,labels" |
| 3643 | - $ref: '#/components/parameters/after' |
| 3644 | - $ref: '#/components/parameters/before' |
| 3645 | - name: timeout |
| 3646 | in: query |
| 3647 | description: | |
| 3648 | Maximum time in milliseconds to wait for the query to complete. |
| 3649 | |
| 3650 | **Format:** Integer (milliseconds) |
| 3651 | |
| 3652 | **Default:** Server default timeout |
| 3653 | |
| 3654 | **Example:** |
| 3655 | - `timeout=30000` - 30 second timeout |
| 3656 | |
| 3657 | 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. |
| 3658 | required: false |
| 3659 | schema: |
| 3660 | type: integer |
| 3661 | format: int64 |
| 3662 | minimum: 1000 |
| 3663 | example: 30000 |
| 3664 | - name: cardinality |
| 3665 | in: query |
| 3666 | description: | |
| 3667 | Limit the number of nodes returned. |
| 3668 | |
| 3669 | **Format:** Integer (maximum nodes) |
| 3670 | |
| 3671 | **Default:** No limit |
| 3672 | |
| 3673 | **Example:** |
| 3674 | - `cardinality=100` - Return at most 100 nodes |
| 3675 | |
| 3676 | **Use Cases:** |
| 3677 | - Prevent huge responses in very large infrastructures |
| 3678 | - Get a sample of nodes for testing |
| 3679 | - Dashboard widgets with limited display space |
| 3680 | |
| 3681 | When exceeded, response indicates how many nodes were omitted. |
| 3682 | required: false |
| 3683 | schema: |
| 3684 | type: integer |
| 3685 | minimum: 1 |
| 3686 | example: 100 |
| 3687 | responses: |
| 3688 | "200": |
| 3689 | description: | |
| 3690 | Success. Returns detailed Netdata agent information. |
| 3691 | |
| 3692 | **Response Structure:** |
| 3693 | The response is a JSON object containing comprehensive agent information grouped by node. |
| 3694 | |
| 3695 | **Top-Level Structure:** |
| 3696 | - `agents`: Array of agent information objects, one per node |
| 3697 | |
| 3698 | **Per-Agent Information Includes:** |
| 3699 | |
| 3700 | **1. Identity:** |
| 3701 | - `machine_guid`: Unique agent identifier (UUID) |
| 3702 | - `hostname`: Node hostname |
| 3703 | - `agent_version`: Netdata version string |
| 3704 | - `agent_commit`: Git commit hash of build |
| 3705 | |
| 3706 | **2. System Information:** |
| 3707 | - `os_name`: Operating system name |
| 3708 | - `os_version`: OS version |
| 3709 | - `kernel_name`: Kernel name |
| 3710 | - `kernel_version`: Kernel version |
| 3711 | - `architecture`: CPU architecture (x86_64, aarch64, etc.) |
| 3712 | - `virtualization`: Virtualization platform (if any) |
| 3713 | - `container`: Container runtime (Docker, LXC, etc.) |
| 3714 | - `container_detection`: How container was detected |
| 3715 | |
| 3716 | **3. Database & Storage:** |
| 3717 | - `database_mode`: Storage mode (dbengine, ram, alloc, none) |
| 3718 | - `database_retention`: Data retention period in seconds |
| 3719 | - `database_size`: Current database size in bytes |
| 3720 | - `page_cache_size`: Page cache size |
| 3721 | - `metrics_stored`: Number of unique metrics |
| 3722 | |
| 3723 | **4. Features & Capabilities:** |
| 3724 | - `ml_enabled`: Machine learning / anomaly detection enabled |
| 3725 | - `ml_models_running`: Number of ML models active |
| 3726 | - `aclk_available`: Cloud connectivity available |
| 3727 | - `aclk_status`: Cloud connection status |
| 3728 | - `stream_compression`: Streaming compression supported |
| 3729 | - `web_enabled`: Web server enabled |
| 3730 | |
| 3731 | **5. Collection Status:** |
| 3732 | - `charts_count`: Number of charts being collected |
| 3733 | - `dimensions_count`: Number of dimensions (time-series) |
| 3734 | - `collectors_count`: Number of active collectors |
| 3735 | - `update_every`: Collection frequency in seconds |
| 3736 | - `history`: Retention in seconds |
| 3737 | - `memory_mode`: Memory storage mode |
| 3738 | |
| 3739 | **6. Host Labels:** |
| 3740 | - `host_labels`: Object containing all host labels |
| 3741 | - Includes automatic labels (_os_name, _architecture, etc.) |
| 3742 | - Includes custom labels assigned by user |
| 3743 | - May include cloud provider labels |
| 3744 | |
| 3745 | **7. Timestamps:** |
| 3746 | - `first_time_t`: Timestamp of oldest data point |
| 3747 | - `last_time_t`: Timestamp of newest data point |
| 3748 | - `now`: Current server time |
| 3749 | |
| 3750 | **8. Streaming Information (if applicable):** |
| 3751 | - `stream_status`: Streaming status (parent/child) |
| 3752 | - `stream_parents`: Parent nodes (if child) |
| 3753 | - `stream_children`: Child nodes (if parent) |
| 3754 | |
| 3755 | **Example Response Structure:** |
| 3756 | ```json |
| 3757 | { |
| 3758 | "agents": [ |
| 3759 | { |
| 3760 | "machine_guid": "550e8400-e29b-41d4-a716-446655440000", |
| 3761 | "hostname": "web-server-01", |
| 3762 | "agent_version": "v1.40.0", |
| 3763 | "os_name": "ubuntu", |
| 3764 | "os_version": "22.04", |
| 3765 | "kernel_version": "5.15.0", |
| 3766 | "architecture": "x86_64", |
| 3767 | "database_mode": "dbengine", |
| 3768 | "database_retention": 86400, |
| 3769 | "ml_enabled": true, |
| 3770 | "charts_count": 425, |
| 3771 | "dimensions_count": 2850, |
| 3772 | "update_every": 1, |
| 3773 | "host_labels": { |
| 3774 | "_os_name": "ubuntu", |
| 3775 | "_architecture": "x86_64", |
| 3776 | "environment": "production", |
| 3777 | "tier": "web" |
| 3778 | } |
| 3779 | } |
| 3780 | ] |
| 3781 | } |
| 3782 | ``` |
| 3783 | |
| 3784 | **Response Characteristics:** |
| 3785 | - Content-Type: application/json |
| 3786 | - Can be cached (agent info changes infrequently) |
| 3787 | - Complete metadata without time-series data |
| 3788 | - Lightweight and fast to generate |
| 3789 | |
| 3790 | **Filtering:** |
| 3791 | Response respects scope_nodes/nodes filters and cardinality limits. |
| 3792 | content: |
| 3793 | application/json: |
| 3794 | schema: |
| 3795 | type: object |
| 3796 | description: Comprehensive Netdata agent information |
| 3797 | "400": |
| 3798 | description: | |
| 3799 | Bad request. Common causes: |
| 3800 | - Invalid parameter values |
| 3801 | - Malformed filter patterns |
| 3802 | "500": |
| 3803 | description: Internal server error during info retrieval. |
| 3804 | /api/v3/node_instances: |
| 3805 | get: |
| 3806 | operationId: node_instances_v3 |
| 3807 | tags: |
| 3808 | - nodes |
| 3809 | summary: Retrieve chart instances organized by node across the infrastructure |
| 3810 | description: | |
| 3811 | 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. |
| 3812 | |
| 3813 | **What are Node Instances?** |
| 3814 | Node instances represent the specific chart instances (individual monitoring targets) on each node: |
| 3815 | - Each node may have multiple instances of the same chart type |
| 3816 | - Examples: Multiple disks (sda, sdb, sdc), multiple network interfaces (eth0, eth1) |
| 3817 | - Instances represent the specific entities being monitored |
| 3818 | |
| 3819 | **Example:** |
| 3820 | For disk monitoring: |
| 3821 | - Node: `web-server-01` |
| 3822 | - Instances: `disk.sda`, `disk.sdb`, `disk.nvme0n1` |
| 3823 | - Node: `db-server-01` |
| 3824 | - Instances: `disk.sda`, `disk.sdb` |
| 3825 | |
| 3826 | **Difference from Other Endpoints:** |
| 3827 | - **`/api/v3/nodes`:** Returns lightweight node list |
| 3828 | - **`/api/v3/info`:** Returns detailed agent information |
| 3829 | - **`/api/v3/node_instances`:** Returns what chart instances each node has (what's being monitored) |
| 3830 | - **`/api/v3/contexts`:** Returns contexts aggregated across all nodes |
| 3831 | |
| 3832 | **Use Cases:** |
| 3833 | - **Infrastructure Discovery:** What devices/services are monitored on each node |
| 3834 | - **Capacity Planning:** Understand monitoring coverage per node |
| 3835 | - **Configuration Verification:** Verify expected charts are collecting |
| 3836 | - **Collector Status:** See which collectors are active per node |
| 3837 | - **Instance Inventory:** Complete catalog of monitored entities |
| 3838 | - **Troubleshooting:** Find which nodes monitor specific instances |
| 3839 | |
| 3840 | **Response Organization:** |
| 3841 | Results are organized hierarchically: |
| 3842 | 1. **By Node:** Top-level grouping by node hostname |
| 3843 | 2. **By Context:** Charts grouped by their context (e.g., disk.space) |
| 3844 | 3. **By Instance:** Individual chart instances within each context |
| 3845 | |
| 3846 | **Performance Characteristics:** |
| 3847 | - Medium query cost (metadata aggregation across nodes) |
| 3848 | - Response size grows with number of nodes and instances |
| 3849 | - Can be filtered to reduce response size |
| 3850 | - Results can be cached (instances change infrequently) |
| 3851 | |
| 3852 | **Example Query Patterns:** |
| 3853 | ``` |
| 3854 | # Get all instances across all nodes |
| 3855 | GET /api/v3/node_instances |
| 3856 | |
| 3857 | # Get instances for specific nodes |
| 3858 | GET /api/v3/node_instances?nodes=web-server-01,db-server-01 |
| 3859 | |
| 3860 | # Get instances for nodes matching pattern |
| 3861 | GET /api/v3/node_instances?scope_nodes=prod-* |
| 3862 | |
| 3863 | # Limit response size |
| 3864 | GET /api/v3/node_instances?cardinality=100 |
| 3865 | ``` |
| 3866 | |
| 3867 | **Response Includes:** |
| 3868 | - Node identification (hostname, machine_guid) |
| 3869 | - Agent information (version, capabilities) |
| 3870 | - All chart instances organized by context |
| 3871 | - Instance-specific metadata (labels, units, dimensions) |
| 3872 | - Instance collection status |
| 3873 | |
| 3874 | **Security & Access Control:** |
| 3875 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 3876 | - **Default Access:** Public (no authentication required) |
| 3877 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 3878 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 3879 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 3880 | security: |
| 3881 | - {} |
| 3882 | - bearerAuth: [] |
| 3883 | parameters: |
| 3884 | - name: scope_nodes |
| 3885 | in: query |
| 3886 | description: | |
| 3887 | Filter to specific nodes using pattern matching. |
| 3888 | |
| 3889 | **Pattern Syntax:** |
| 3890 | - `*` matches any characters |
| 3891 | - Space-separated for multiple patterns |
| 3892 | - `!` prefix excludes |
| 3893 | - Example: `prod-* !prod-test*` |
| 3894 | |
| 3895 | **Examples:** |
| 3896 | - `scope_nodes=web*` - All web servers |
| 3897 | - `scope_nodes=db-* cache-*` - Database and cache nodes |
| 3898 | - `scope_nodes=* !test*` - All except test nodes |
| 3899 | |
| 3900 | When not specified, returns instances from all nodes. |
| 3901 | required: false |
| 3902 | schema: |
| 3903 | type: string |
| 3904 | example: "prod-*" |
| 3905 | - name: nodes |
| 3906 | in: query |
| 3907 | description: | |
| 3908 | Filter to specific nodes by exact names. |
| 3909 | |
| 3910 | **Format:** Comma or pipe-separated exact names |
| 3911 | |
| 3912 | **Examples:** |
| 3913 | - `nodes=web-server-01` - Single node |
| 3914 | - `nodes=web-01,db-01` - Multiple nodes |
| 3915 | |
| 3916 | **Best Practice:** Use `nodes` for exact names, `scope_nodes` for patterns. |
| 3917 | |
| 3918 | When not specified, returns instances from all nodes. |
| 3919 | required: false |
| 3920 | schema: |
| 3921 | type: string |
| 3922 | example: "web-server-01,db-server-01" |
| 3923 | - name: options |
| 3924 | in: query |
| 3925 | description: | |
| 3926 | Control response detail level and included information. |
| 3927 | |
| 3928 | **Available Options:** |
| 3929 | - `full` or `all` - Complete instance information |
| 3930 | - `labels` - Include instance labels |
| 3931 | - `uuids` - Include UUIDs and identifiers |
| 3932 | - `deleted` - Include deleted/offline instances |
| 3933 | - `hidden` - Include hidden instances |
| 3934 | - `instances` or `charts` - Include chart instances (default) |
| 3935 | - `metrics` or `dimensions` - Include dimension details |
| 3936 | |
| 3937 | **Examples:** |
| 3938 | - `options=full` - All information |
| 3939 | - `options=labels,dimensions` - Labels and dimension details |
| 3940 | - `options=labels|uuids` - Pipe separator |
| 3941 | |
| 3942 | **Default:** Returns basic instance information without excessive detail. |
| 3943 | required: false |
| 3944 | schema: |
| 3945 | type: string |
| 3946 | example: "full,labels,dimensions" |
| 3947 | - $ref: '#/components/parameters/after' |
| 3948 | - $ref: '#/components/parameters/before' |
| 3949 | - name: timeout |
| 3950 | in: query |
| 3951 | description: | |
| 3952 | Maximum time in milliseconds to wait for query completion. |
| 3953 | |
| 3954 | **Format:** Integer (milliseconds) |
| 3955 | |
| 3956 | **Default:** Server default timeout |
| 3957 | |
| 3958 | **Example:** `timeout=30000` (30 seconds) |
| 3959 | |
| 3960 | For large multi-node infrastructures, you may need to increase timeout to allow complete instance enumeration. |
| 3961 | required: false |
| 3962 | schema: |
| 3963 | type: integer |
| 3964 | format: int64 |
| 3965 | minimum: 1000 |
| 3966 | example: 30000 |
| 3967 | - name: cardinality |
| 3968 | in: query |
| 3969 | description: | |
| 3970 | Limit the number of instances returned per node. |
| 3971 | |
| 3972 | **Format:** Integer (max instances per node) |
| 3973 | |
| 3974 | **Default:** No limit |
| 3975 | |
| 3976 | **Example:** `cardinality=500` - At most 500 instances per node |
| 3977 | |
| 3978 | **Use Cases:** |
| 3979 | - Prevent huge responses from nodes with many instances |
| 3980 | - Sample instances for testing |
| 3981 | - Dashboard widgets with limited space |
| 3982 | |
| 3983 | When exceeded, response indicates how many instances were omitted per node. |
| 3984 | required: false |
| 3985 | schema: |
| 3986 | type: integer |
| 3987 | minimum: 1 |
| 3988 | example: 500 |
| 3989 | responses: |
| 3990 | "200": |
| 3991 | description: | |
| 3992 | Success. Returns chart instances organized by node. |
| 3993 | |
| 3994 | **Response Structure:** |
| 3995 | ```json |
| 3996 | { |
| 3997 | "nodes": [ |
| 3998 | { |
| 3999 | "machine_guid": "uuid", |
| 4000 | "hostname": "web-server-01", |
| 4001 | "agent_version": "v1.40.0", |
| 4002 | "contexts": [ |
| 4003 | { |
| 4004 | "context": "disk.space", |
| 4005 | "instances": [ |
| 4006 | { |
| 4007 | "id": "disk.sda", |
| 4008 | "name": "disk sda", |
| 4009 | "family": "sda", |
| 4010 | "labels": {...}, |
| 4011 | "dimensions": [...], |
| 4012 | "status": "active" |
| 4013 | }, |
| 4014 | { |
| 4015 | "id": "disk.sdb", |
| 4016 | "name": "disk sdb", |
| 4017 | "family": "sdb", |
| 4018 | "labels": {...}, |
| 4019 | "dimensions": [...], |
| 4020 | "status": "active" |
| 4021 | } |
| 4022 | ] |
| 4023 | }, |
| 4024 | { |
| 4025 | "context": "net.net", |
| 4026 | "instances": [ |
| 4027 | { |
| 4028 | "id": "net.eth0", |
| 4029 | "name": "eth0", |
| 4030 | "family": "eth0", |
| 4031 | "labels": {...}, |
| 4032 | "dimensions": [...], |
| 4033 | "status": "active" |
| 4034 | } |
| 4035 | ] |
| 4036 | } |
| 4037 | ] |
| 4038 | } |
| 4039 | ] |
| 4040 | } |
| 4041 | ``` |
| 4042 | |
| 4043 | **Response Fields:** |
| 4044 | |
| 4045 | **Node Level:** |
| 4046 | - `machine_guid`: Unique node identifier |
| 4047 | - `hostname`: Node hostname |
| 4048 | - `agent_version`: Netdata version on this node |
| 4049 | - `contexts`: Array of contexts with their instances |
| 4050 | |
| 4051 | **Context Level:** |
| 4052 | - `context`: Context name (e.g., "disk.space", "system.cpu") |
| 4053 | - `instances`: Array of chart instances for this context |
| 4054 | |
| 4055 | **Instance Level:** |
| 4056 | - `id`: Chart instance ID (e.g., "disk.sda") |
| 4057 | - `name`: Human-readable instance name |
| 4058 | - `family`: Chart family/grouping |
| 4059 | - `labels`: Instance-specific labels |
| 4060 | - `dimensions`: Array of dimensions (metrics) collected |
| 4061 | - `status`: Collection status (active, stale, offline) |
| 4062 | - `units`: Unit of measurement |
| 4063 | - `chart_type`: Chart visualization type |
| 4064 | - `priority`: Display priority |
| 4065 | |
| 4066 | **Dimension Information (when options=dimensions):** |
| 4067 | - `id`: Dimension identifier |
| 4068 | - `name`: Dimension display name |
| 4069 | - `algorithm`: Aggregation algorithm |
| 4070 | - `multiplier`, `divisor`: Value transformation |
| 4071 | |
| 4072 | **Label Information (when options=labels):** |
| 4073 | - Instance labels provide additional metadata |
| 4074 | - Examples: disk_type=ssd, interface_speed=1000, mount_point=/ |
| 4075 | |
| 4076 | **Response Characteristics:** |
| 4077 | - Content-Type: application/json |
| 4078 | - Cacheable (instances change infrequently) |
| 4079 | - Size grows with number of nodes and instances |
| 4080 | - Organized hierarchically for easy navigation |
| 4081 | |
| 4082 | **Filtering:** |
| 4083 | Response respects scope_nodes/nodes filters and cardinality limits. |
| 4084 | content: |
| 4085 | application/json: |
| 4086 | schema: |
| 4087 | type: object |
| 4088 | description: Chart instances organized by node |
| 4089 | "400": |
| 4090 | description: | |
| 4091 | Bad request. Common causes: |
| 4092 | - Invalid parameter values |
| 4093 | - Malformed filter patterns |
| 4094 | "500": |
| 4095 | description: Internal server error during instance enumeration. |
| 4096 | /api/v3/stream_path: |
| 4097 | get: |
| 4098 | operationId: stream_path |
| 4099 | tags: |
| 4100 | - nodes |
| 4101 | summary: Retrieve streaming topology path for nodes |
| 4102 | description: | |
| 4103 | **V3 SPECIFIC ENDPOINT** |
| 4104 | |
| 4105 | Returns the streaming path and topology showing how nodes are connected in the Netdata infrastructure. |
| 4106 | This endpoint reveals the parent-child relationships between nodes, showing which nodes stream data |
| 4107 | to which parents, creating a hierarchical view of the monitoring infrastructure. |
| 4108 | |
| 4109 | **Streaming Topology:** |
| 4110 | - **Parent nodes**: Nodes that receive streaming data from child nodes |
| 4111 | - **Child nodes**: Nodes that send their metrics to parent nodes for centralization |
| 4112 | - **Streaming path**: The complete chain from child → parent → grandparent (if any) |
| 4113 | |
| 4114 | **Use Cases:** |
| 4115 | - Understand infrastructure hierarchy and data flow |
| 4116 | - Identify parent nodes that aggregate data from multiple children |
| 4117 | - Debug streaming connectivity issues |
| 4118 | - Plan infrastructure changes and reorganization |
| 4119 | - Visualize the complete monitoring topology |
| 4120 | |
| 4121 | **Common Usage Patterns:** |
| 4122 | |
| 4123 | 1. **Get complete streaming topology:** |
| 4124 | ``` |
| 4125 | /api/v3/stream_path |
| 4126 | ``` |
| 4127 | |
| 4128 | 2. **Filter by specific nodes:** |
| 4129 | ``` |
| 4130 | /api/v3/stream_path?nodes=child-node-1|child-node-2 |
| 4131 | ``` |
| 4132 | |
| 4133 | 3. **Scope to nodes matching pattern:** |
| 4134 | ``` |
| 4135 | /api/v3/stream_path?scope_nodes=prod-* |
| 4136 | ``` |
| 4137 | |
| 4138 | **Response Structure:** |
| 4139 | The response includes nodes organized by their streaming relationships, showing: |
| 4140 | - Node hostnames and machine GUIDs |
| 4141 | - Parent-child relationships |
| 4142 | - Streaming connection status (live/stale/offline) |
| 4143 | - Complete path from each child to root parent |
| 4144 | |
| 4145 | **Security & Access Control:** |
| 4146 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 4147 | - **Default Access:** Public (no authentication required) |
| 4148 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 4149 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 4150 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 4151 | security: |
| 4152 | - {} |
| 4153 | - bearerAuth: [] |
| 4154 | parameters: |
| 4155 | - name: scope_nodes |
| 4156 | in: query |
| 4157 | required: false |
| 4158 | description: | |
| 4159 | Simple pattern to match node hostnames for scope filtering. Uses Netdata's simple pattern |
| 4160 | matching (not regex). Matched nodes define the scope for topology analysis. |
| 4161 | |
| 4162 | **Pattern Syntax:** |
| 4163 | - `*` matches any number of characters |
| 4164 | - Use `|` to separate multiple patterns (OR logic) |
| 4165 | - Matches are case-insensitive |
| 4166 | - No regex support - only simple wildcards |
| 4167 | |
| 4168 | **Examples:** |
| 4169 | - `prod-*` - All production nodes |
| 4170 | - `*-web-*` - All web server nodes |
| 4171 | - `db-*|cache-*` - All database or cache nodes |
| 4172 | - `*` - All nodes (default) |
| 4173 | schema: |
| 4174 | type: string |
| 4175 | default: "*" |
| 4176 | example: "prod-*" |
| 4177 | - name: nodes |
| 4178 | in: query |
| 4179 | required: false |
| 4180 | description: | |
| 4181 | Simple pattern to filter which nodes to include in the streaming path response. |
| 4182 | After scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes. |
| 4183 | |
| 4184 | **Difference from scope_nodes:** |
| 4185 | - `scope_nodes` defines what nodes to analyze for relationships |
| 4186 | - `nodes` filters which nodes to include in the output |
| 4187 | |
| 4188 | **Examples:** |
| 4189 | - `web-*` - Only show web server nodes in output |
| 4190 | - `parent-*` - Only show parent nodes |
| 4191 | - Specific hostnames: `node1|node2|node3` |
| 4192 | schema: |
| 4193 | type: string |
| 4194 | default: "*" |
| 4195 | example: "web-*" |
| 4196 | - name: options |
| 4197 | in: query |
| 4198 | required: false |
| 4199 | description: | |
| 4200 | Comma-separated list of options to control response content and format. |
| 4201 | |
| 4202 | **Available Options:** |
| 4203 | - `minify` - Minimize JSON output (no pretty-printing) |
| 4204 | - `debug` - Include debug information about streaming connections |
| 4205 | - `raw` - Include raw streaming metadata |
| 4206 | |
| 4207 | **Examples:** |
| 4208 | - `minify` - Compact JSON response |
| 4209 | - `debug,raw` - Debug mode with raw metadata |
| 4210 | schema: |
| 4211 | type: string |
| 4212 | example: "debug" |
| 4213 | - name: timeout |
| 4214 | in: query |
| 4215 | required: false |
| 4216 | description: | |
| 4217 | Maximum time in seconds to wait for the query to complete before timing out. |
| 4218 | |
| 4219 | **Guidelines:** |
| 4220 | - Recommended: 30-60 seconds for most queries |
| 4221 | - Large infrastructures may need longer timeouts |
| 4222 | - Queries timeout if streaming metadata collection takes too long |
| 4223 | schema: |
| 4224 | type: integer |
| 4225 | minimum: 1 |
| 4226 | default: 60 |
| 4227 | example: 30 |
| 4228 | - name: cardinality |
| 4229 | in: query |
| 4230 | required: false |
| 4231 | description: | |
| 4232 | Maximum number of nodes to include in the response to prevent overwhelming large responses. |
| 4233 | When this limit is exceeded, the response will indicate how many nodes were omitted. |
| 4234 | |
| 4235 | **Purpose:** |
| 4236 | - Prevent memory exhaustion from very large infrastructures |
| 4237 | - Control response size for performance |
| 4238 | - Useful when exploring large node hierarchies incrementally |
| 4239 | |
| 4240 | **Recommendations:** |
| 4241 | - Small infrastructures (< 50 nodes): Use default or increase |
| 4242 | - Medium infrastructures (50-500 nodes): 200-500 |
| 4243 | - Large infrastructures (> 500 nodes): Use filtering or increase limit carefully |
| 4244 | schema: |
| 4245 | type: integer |
| 4246 | minimum: 1 |
| 4247 | maximum: 10000 |
| 4248 | default: 1000 |
| 4249 | example: 500 |
| 4250 | responses: |
| 4251 | "200": |
| 4252 | description: | |
| 4253 | Successfully retrieved streaming topology path information. |
| 4254 | |
| 4255 | Returns nodes with their streaming relationships, showing parent-child hierarchy, |
| 4256 | connection status, and complete paths from children to root parents. |
| 4257 | content: |
| 4258 | application/json: |
| 4259 | schema: |
| 4260 | type: object |
| 4261 | properties: |
| 4262 | nodes: |
| 4263 | type: array |
| 4264 | description: Array of nodes with streaming path information |
| 4265 | items: |
| 4266 | type: object |
| 4267 | properties: |
| 4268 | hostname: |
| 4269 | type: string |
| 4270 | description: Node hostname |
| 4271 | machine_guid: |
| 4272 | type: string |
| 4273 | description: Unique node identifier |
| 4274 | parent: |
| 4275 | type: string |
| 4276 | description: Hostname of parent node (if any) |
| 4277 | parent_guid: |
| 4278 | type: string |
| 4279 | description: Machine GUID of parent node |
| 4280 | streaming_status: |
| 4281 | type: string |
| 4282 | enum: [live, stale, offline] |
| 4283 | description: Current streaming connection status |
| 4284 | path: |
| 4285 | type: array |
| 4286 | description: Complete path from this node to root parent |
| 4287 | items: |
| 4288 | type: string |
| 4289 | omitted: |
| 4290 | type: integer |
| 4291 | description: Number of nodes omitted due to cardinality limit |
| 4292 | "400": |
| 4293 | description: Invalid parameters provided (e.g., invalid pattern syntax). |
| 4294 | "500": |
| 4295 | description: Internal server error during streaming topology retrieval. |
| 4296 | "504": |
| 4297 | description: Query timeout - streaming topology collection took too long. |
| 4298 | /api/v3/versions: |
| 4299 | get: |
| 4300 | operationId: versions3 |
| 4301 | tags: |
| 4302 | - versions |
| 4303 | summary: Retrieve Netdata agent version information across nodes |
| 4304 | description: | |
| 4305 | Returns version information for Netdata agents running on monitored nodes. |
| 4306 | This endpoint provides visibility into the software versions deployed across your infrastructure, |
| 4307 | helping identify version mismatches, outdated agents, and upgrade planning. |
| 4308 | |
| 4309 | **Version Information Includes:** |
| 4310 | - Netdata agent version string (e.g., "v1.40.0") |
| 4311 | - Build information and commit hash |
| 4312 | - Protocol versions supported |
| 4313 | - Feature capabilities based on version |
| 4314 | |
| 4315 | **Use Cases:** |
| 4316 | - **Version audit**: Identify which nodes run which versions |
| 4317 | - **Upgrade planning**: Find nodes that need updates |
| 4318 | - **Compatibility checking**: Ensure version compatibility across infrastructure |
| 4319 | - **Feature availability**: Determine which features are available on which nodes |
| 4320 | - **Security compliance**: Identify nodes running vulnerable versions |
| 4321 | |
| 4322 | **Common Usage Patterns:** |
| 4323 | |
| 4324 | 1. **Get versions of all nodes:** |
| 4325 | ``` |
| 4326 | /api/v3/versions |
| 4327 | ``` |
| 4328 | |
| 4329 | 2. **Check versions of specific nodes:** |
| 4330 | ``` |
| 4331 | /api/v3/versions?nodes=prod-* |
| 4332 | ``` |
| 4333 | |
| 4334 | 3. **Scope to production infrastructure:** |
| 4335 | ``` |
| 4336 | /api/v3/versions?scope_nodes=prod-* |
| 4337 | ``` |
| 4338 | |
| 4339 | **Response Structure:** |
| 4340 | Returns version information grouped by node, showing: |
| 4341 | - Agent version string |
| 4342 | - Build timestamp |
| 4343 | - Git commit hash |
| 4344 | - Protocol versions |
| 4345 | - Feature flags and capabilities |
| 4346 | |
| 4347 | **Security & Access Control:** |
| 4348 | - 🔓 **Always Public API** - This endpoint is always accessible without authentication |
| 4349 | - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions |
| 4350 | - **No Authentication:** Cannot be restricted by any configuration |
| 4351 | - **Access:** Available to anyone who can reach the agent's HTTP endpoint |
| 4352 | parameters: |
| 4353 | - name: scope_nodes |
| 4354 | in: query |
| 4355 | required: false |
| 4356 | description: | |
| 4357 | Simple pattern to match node hostnames for scope filtering. Uses Netdata's simple pattern |
| 4358 | matching (not regex). Matched nodes define the scope for version information retrieval. |
| 4359 | |
| 4360 | **Pattern Syntax:** |
| 4361 | - `*` matches any number of characters |
| 4362 | - Use `|` to separate multiple patterns (OR logic) |
| 4363 | - Matches are case-insensitive |
| 4364 | - No regex support - only simple wildcards |
| 4365 | |
| 4366 | **Examples:** |
| 4367 | - `prod-*` - All production nodes |
| 4368 | - `*-db-*` - All database nodes |
| 4369 | - `web-*|app-*` - All web or application nodes |
| 4370 | - `*` - All nodes (default) |
| 4371 | schema: |
| 4372 | type: string |
| 4373 | default: "*" |
| 4374 | example: "prod-*" |
| 4375 | - name: nodes |
| 4376 | in: query |
| 4377 | required: false |
| 4378 | description: | |
| 4379 | Simple pattern to filter which nodes to include in the version information response. |
| 4380 | After scope is determined, this filters the results. Uses the same pattern syntax as scope_nodes. |
| 4381 | |
| 4382 | **Difference from scope_nodes:** |
| 4383 | - `scope_nodes` defines what nodes to analyze |
| 4384 | - `nodes` filters which nodes appear in the output |
| 4385 | |
| 4386 | **Examples:** |
| 4387 | - `old-*` - Only show nodes matching "old-*" pattern |
| 4388 | - Specific hostnames: `node1|node2|node3` |
| 4389 | schema: |
| 4390 | type: string |
| 4391 | default: "*" |
| 4392 | example: "*" |
| 4393 | - name: options |
| 4394 | in: query |
| 4395 | required: false |
| 4396 | description: | |
| 4397 | Comma-separated list of options to control response content and format. |
| 4398 | |
| 4399 | **Available Options:** |
| 4400 | - `minify` - Minimize JSON output (no pretty-printing) |
| 4401 | - `debug` - Include additional debug information |
| 4402 | - `raw` - Include raw version metadata |
| 4403 | |
| 4404 | **Examples:** |
| 4405 | - `minify` - Compact JSON response |
| 4406 | - `debug,raw` - Debug mode with raw metadata |
| 4407 | schema: |
| 4408 | type: string |
| 4409 | example: "debug" |
| 4410 | - name: timeout |
| 4411 | in: query |
| 4412 | required: false |
| 4413 | description: | |
| 4414 | Maximum time in seconds to wait for the query to complete before timing out. |
| 4415 | |
| 4416 | **Guidelines:** |
| 4417 | - Recommended: 10-30 seconds for most queries |
| 4418 | - Version information is usually quick to retrieve |
| 4419 | - Timeout mainly applies to very large infrastructures |
| 4420 | schema: |
| 4421 | type: integer |
| 4422 | minimum: 1 |
| 4423 | default: 60 |
| 4424 | example: 10 |
| 4425 | - name: cardinality |
| 4426 | in: query |
| 4427 | required: false |
| 4428 | description: | |
| 4429 | Maximum number of nodes to include in the response to prevent overwhelming large responses. |
| 4430 | When this limit is exceeded, the response will indicate how many nodes were omitted. |
| 4431 | |
| 4432 | **Purpose:** |
| 4433 | - Prevent memory exhaustion from very large infrastructures |
| 4434 | - Control response size for performance |
| 4435 | - Useful when exploring large node sets incrementally |
| 4436 | |
| 4437 | **Recommendations:** |
| 4438 | - Small infrastructures (< 100 nodes): Use default |
| 4439 | - Medium infrastructures (100-1000 nodes): 500-1000 |
| 4440 | - Large infrastructures (> 1000 nodes): Use filtering or increase limit carefully |
| 4441 | schema: |
| 4442 | type: integer |
| 4443 | minimum: 1 |
| 4444 | maximum: 10000 |
| 4445 | default: 1000 |
| 4446 | example: 500 |
| 4447 | responses: |
| 4448 | "200": |
| 4449 | description: | |
| 4450 | Successfully retrieved version information. |
| 4451 | |
| 4452 | Returns version data for each node including agent version, build info, |
| 4453 | protocol versions, and feature capabilities. |
| 4454 | content: |
| 4455 | application/json: |
| 4456 | schema: |
| 4457 | type: object |
| 4458 | properties: |
| 4459 | versions: |
| 4460 | type: array |
| 4461 | description: Array of version information per node |
| 4462 | items: |
| 4463 | type: object |
| 4464 | properties: |
| 4465 | hostname: |
| 4466 | type: string |
| 4467 | description: Node hostname |
| 4468 | machine_guid: |
| 4469 | type: string |
| 4470 | description: Unique node identifier |
| 4471 | version: |
| 4472 | type: string |
| 4473 | description: Netdata agent version string |
| 4474 | example: "v1.40.0" |
| 4475 | build_info: |
| 4476 | type: string |
| 4477 | description: Build information and timestamp |
| 4478 | commit_hash: |
| 4479 | type: string |
| 4480 | description: Git commit hash of the build |
| 4481 | protocol_version: |
| 4482 | type: integer |
| 4483 | description: Streaming protocol version supported |
| 4484 | features: |
| 4485 | type: array |
| 4486 | description: Feature flags and capabilities |
| 4487 | items: |
| 4488 | type: string |
| 4489 | omitted: |
| 4490 | type: integer |
| 4491 | description: Number of nodes omitted due to cardinality limit |
| 4492 | "400": |
| 4493 | description: Invalid parameters provided (e.g., invalid pattern syntax). |
| 4494 | "500": |
| 4495 | description: Internal server error during version information retrieval. |
| 4496 | "504": |
| 4497 | description: Query timeout - version collection took too long. |
| 4498 | /api/v3/progress: |
| 4499 | get: |
| 4500 | operationId: progress3 |
| 4501 | tags: |
| 4502 | - functions |
| 4503 | summary: Track progress of long-running function executions |
| 4504 | description: | |
| 4505 | Monitors the progress of long-running Netdata function executions identified by a transaction ID. |
| 4506 | When executing functions that may take significant time (e.g., data collection, analysis, exports), |
| 4507 | this endpoint allows clients to poll for progress updates and track completion status. |
| 4508 | |
| 4509 | **Function Execution Flow:** |
| 4510 | 1. Client initiates a function execution (e.g., via `/api/v3/function`) |
| 4511 | 2. Function returns immediately with a transaction ID |
| 4512 | 3. Client polls `/api/v3/progress?transaction=<id>` for status updates |
| 4513 | 4. Progress endpoint returns completion percentage and status |
| 4514 | 5. When complete, client retrieves final results |
| 4515 | |
| 4516 | **Progress Information Includes:** |
| 4517 | - **Percentage complete**: 0-100% progress indicator |
| 4518 | - **Status**: running, completed, failed, cancelled |
| 4519 | - **Message**: Human-readable status description |
| 4520 | - **Remaining time estimate**: If available |
| 4521 | |
| 4522 | **Use Cases:** |
| 4523 | - **Long data exports**: Track progress of large data export operations |
| 4524 | - **Analysis functions**: Monitor CPU-intensive analysis tasks |
| 4525 | - **Batch operations**: Track multi-step batch processing |
| 4526 | - **User experience**: Provide progress feedback in UI applications |
| 4527 | |
| 4528 | **Polling Best Practices:** |
| 4529 | - Poll every 1-2 seconds for responsive updates |
| 4530 | - Implement exponential backoff for completed/failed states |
| 4531 | - Set reasonable timeouts (functions may take minutes) |
| 4532 | - Handle cancellation gracefully |
| 4533 | |
| 4534 | **Common Usage Patterns:** |
| 4535 | |
| 4536 | 1. **Poll for function progress:** |
| 4537 | ``` |
| 4538 | /api/v3/progress?transaction=550e8400-e29b-41d4-a716-446655440000 |
| 4539 | ``` |
| 4540 | |
| 4541 | 2. **Integration with function execution:** |
| 4542 | ```javascript |
| 4543 | // 1. Start function |
| 4544 | const response = await fetch('/api/v3/function?...'); |
| 4545 | const { transaction } = await response.json(); |
| 4546 | |
| 4547 | // 2. Poll for progress |
| 4548 | const interval = setInterval(async () => { |
| 4549 | const progress = await fetch(`/api/v3/progress?transaction=${transaction}`); |
| 4550 | const { percentage, status } = await progress.json(); |
| 4551 | |
| 4552 | if (status === 'completed') { |
| 4553 | clearInterval(interval); |
| 4554 | // Fetch final results |
| 4555 | } |
| 4556 | }, 1000); |
| 4557 | ``` |
| 4558 | |
| 4559 | **Transaction ID Format:** |
| 4560 | - UUID v4 format: `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` |
| 4561 | - Returned by function execution endpoints |
| 4562 | - Valid for the lifetime of the function execution |
| 4563 | - Expires after completion or timeout |
| 4564 | |
| 4565 | **Security & Access Control:** |
| 4566 | - 🔓 **Always Public API** - This endpoint is always accessible without authentication |
| 4567 | - **No Restrictions:** Not subject to bearer protection or IP-based ACL restrictions |
| 4568 | - **No Authentication:** Cannot be restricted by any configuration |
| 4569 | - **Access:** Available to anyone who can reach the agent's HTTP endpoint |
| 4570 | parameters: |
| 4571 | - name: transaction |
| 4572 | in: query |
| 4573 | required: true |
| 4574 | description: | |
| 4575 | Transaction ID (UUID) of the function execution to track. This ID is returned |
| 4576 | when initiating a function execution via `/api/v3/function` or similar endpoints. |
| 4577 | |
| 4578 | **UUID Format:** |
| 4579 | - Standard UUID v4 format |
| 4580 | - Example: `550e8400-e29b-41d4-a716-446655440000` |
| 4581 | - Case-insensitive |
| 4582 | |
| 4583 | **Transaction Lifecycle:** |
| 4584 | - **Created**: When function execution starts |
| 4585 | - **Active**: While function is running |
| 4586 | - **Expired**: After completion, failure, or timeout |
| 4587 | - **Retention**: Transaction state kept briefly after completion for final status retrieval |
| 4588 | |
| 4589 | **Invalid Transaction Handling:** |
| 4590 | - Missing transaction: Returns 400 Bad Request |
| 4591 | - Malformed UUID: Returns 400 Bad Request |
| 4592 | - Expired transaction: Returns 404 Not Found |
| 4593 | - Unknown transaction: Returns 404 Not Found |
| 4594 | schema: |
| 4595 | type: string |
| 4596 | format: uuid |
| 4597 | example: "550e8400-e29b-41d4-a716-446655440000" |
| 4598 | responses: |
| 4599 | "200": |
| 4600 | description: | |
| 4601 | Successfully retrieved progress information for the transaction. |
| 4602 | |
| 4603 | Returns current progress status including percentage complete, state, and optional message. |
| 4604 | content: |
| 4605 | application/json: |
| 4606 | schema: |
| 4607 | type: object |
| 4608 | properties: |
| 4609 | transaction: |
| 4610 | type: string |
| 4611 | format: uuid |
| 4612 | description: The transaction ID being tracked |
| 4613 | status: |
| 4614 | type: string |
| 4615 | enum: [running, completed, failed, cancelled] |
| 4616 | description: Current status of the function execution |
| 4617 | percentage: |
| 4618 | type: integer |
| 4619 | minimum: 0 |
| 4620 | maximum: 100 |
| 4621 | description: Completion percentage (0-100) |
| 4622 | message: |
| 4623 | type: string |
| 4624 | description: Human-readable status message or error description |
| 4625 | done: |
| 4626 | type: integer |
| 4627 | description: Number of items processed (if applicable) |
| 4628 | all: |
| 4629 | type: integer |
| 4630 | description: Total number of items to process (if applicable) |
| 4631 | eta_seconds: |
| 4632 | type: integer |
| 4633 | description: Estimated time remaining in seconds (if available) |
| 4634 | examples: |
| 4635 | running: |
| 4636 | value: |
| 4637 | transaction: "550e8400-e29b-41d4-a716-446655440000" |
| 4638 | status: "running" |
| 4639 | percentage: 45 |
| 4640 | message: "Processing data..." |
| 4641 | done: 450 |
| 4642 | all: 1000 |
| 4643 | eta_seconds: 30 |
| 4644 | completed: |
| 4645 | value: |
| 4646 | transaction: "550e8400-e29b-41d4-a716-446655440000" |
| 4647 | status: "completed" |
| 4648 | percentage: 100 |
| 4649 | message: "Function execution completed successfully" |
| 4650 | failed: |
| 4651 | value: |
| 4652 | transaction: "550e8400-e29b-41d4-a716-446655440000" |
| 4653 | status: "failed" |
| 4654 | percentage: 67 |
| 4655 | message: "Error: timeout during data collection" |
| 4656 | "400": |
| 4657 | description: | |
| 4658 | Bad request. Common causes: |
| 4659 | - Missing transaction parameter |
| 4660 | - Malformed UUID format |
| 4661 | - Invalid transaction ID format |
| 4662 | "404": |
| 4663 | description: | |
| 4664 | Transaction not found. Possible reasons: |
| 4665 | - Transaction ID does not exist |
| 4666 | - Transaction has expired (completed/failed long ago) |
| 4667 | - Transaction was never created |
| 4668 | "500": |
| 4669 | description: Internal server error during progress tracking. |
| 4670 | /api/v3/function: |
| 4671 | get: |
| 4672 | operationId: function3 |
| 4673 | tags: |
| 4674 | - functions |
| 4675 | summary: Execute a Netdata function on a specific node |
| 4676 | description: | |
| 4677 | Executes a named function on a Netdata agent to retrieve live information or trigger actions. |
| 4678 | Functions are plugin-provided operations that can query system state, collect real-time data, |
| 4679 | or perform administrative tasks. |
| 4680 | |
| 4681 | **What are Netdata Functions?** |
| 4682 | Functions extend Netdata beyond passive metric collection by allowing: |
| 4683 | - **Live data queries**: Get current system state (processes, connections, services) |
| 4684 | - **Interactive diagnostics**: Run on-demand checks and analysis |
| 4685 | - **Administrative operations**: Trigger actions like cache clearing or config reloading |
| 4686 | - **Plugin-specific features**: Access specialized capabilities provided by plugins |
| 4687 | |
| 4688 | **Common Functions Include:** |
| 4689 | - `systemd-list-units` - List systemd services and their status |
| 4690 | - `processes` - List currently running processes with resource usage |
| 4691 | - `network-connections` - Show active network connections |
| 4692 | - `mount-points` - Display mounted filesystems |
| 4693 | - `docker-containers` - List Docker containers (if Docker plugin enabled) |
| 4694 | - Many more plugin-specific functions |
| 4695 | |
| 4696 | **Function Discovery:** |
| 4697 | Use `/api/v3/functions` to discover available functions on each node. |
| 4698 | |
| 4699 | **Execution Model:** |
| 4700 | - Functions execute on the target node's agent |
| 4701 | - Results are collected and returned in real-time |
| 4702 | - Long-running functions return a transaction ID for progress tracking |
| 4703 | - Functions may require specific permissions or capabilities |
| 4704 | |
| 4705 | **Use Cases:** |
| 4706 | - **System diagnostics**: Query live system state for troubleshooting |
| 4707 | - **Capacity planning**: Get current resource utilization details |
| 4708 | - **Security auditing**: List processes, connections, open ports |
| 4709 | - **Service management**: Check service status across infrastructure |
| 4710 | - **Interactive dashboards**: Provide drill-down capabilities |
| 4711 | |
| 4712 | **Common Usage Patterns:** |
| 4713 | |
| 4714 | 1. **List running processes:** |
| 4715 | ``` |
| 4716 | /api/v3/function?function=processes |
| 4717 | ``` |
| 4718 | |
| 4719 | 2. **List systemd services:** |
| 4720 | ``` |
| 4721 | /api/v3/function?function=systemd-list-units&timeout=30 |
| 4722 | ``` |
| 4723 | |
| 4724 | 3. **Get network connections:** |
| 4725 | ``` |
| 4726 | /api/v3/function?function=network-connections |
| 4727 | ``` |
| 4728 | |
| 4729 | 4. **Execute with custom timeout for slow operations:** |
| 4730 | ``` |
| 4731 | /api/v3/function?function=docker-containers&timeout=60 |
| 4732 | ``` |
| 4733 | |
| 4734 | **Function Response Formats:** |
| 4735 | - Most functions return JSON data |
| 4736 | - Some may return plain text or formatted output |
| 4737 | - Check Content-Type header for response format |
| 4738 | - Long operations may return transaction ID for `/api/v3/progress` polling |
| 4739 | |
| 4740 | **Security Considerations:** |
| 4741 | - Functions respect user authentication and authorization |
| 4742 | - Some functions may require elevated permissions |
| 4743 | - Function execution is subject to ACL checks |
| 4744 | - Sensitive operations may be restricted by configuration |
| 4745 | |
| 4746 | **Security & Access Control:** |
| 4747 | - 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply |
| 4748 | - **Default Access:** Public (no authentication required) |
| 4749 | - **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token |
| 4750 | - **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf |
| 4751 | - **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external tools |
| 4752 | security: |
| 4753 | - {} |
| 4754 | - bearerAuth: [] |
| 4755 | parameters: |
| 4756 | - name: function |
| 4757 | in: query |
| 4758 | required: true |
| 4759 | description: | |
| 4760 | Name of the function to execute. Each Netdata plugin can provide multiple functions |
| 4761 | with different capabilities. |
| 4762 | |
| 4763 | **Function Names:** |
| 4764 | - Kebab-case naming: `function-name-here` |
| 4765 | - Provided by plugins: different plugins provide different functions |
| 4766 | - Discoverable via `/api/v3/functions` endpoint |
| 4767 | - Case-sensitive |
| 4768 | |
| 4769 | **Common Built-in Functions:** |
| 4770 | - `systemd-list-units` - List systemd services |
| 4771 | - `processes` - Running processes with CPU/memory usage |
| 4772 | - `network-connections` - Active network connections and sockets |
| 4773 | - `mount-points` - Mounted filesystems and usage |
| 4774 | - `ipmi-sensors` - IPMI hardware sensors (if available) |
| 4775 | |
| 4776 | **Plugin-Specific Functions:** |
| 4777 | - Docker plugin: `docker-containers`, `docker-images` |
| 4778 | - Apps plugin: `apps-processes` |
| 4779 | - Logs plugin: `logs-query` |
| 4780 | - And many more depending on enabled plugins |
| 4781 | |
| 4782 | **Invalid Function Names:** |
| 4783 | - Missing function: Returns 400 Bad Request |
| 4784 | - Unknown function: Returns 404 Not Found or function-specific error |
| 4785 | - Disabled function: Returns 403 Forbidden |
| 4786 | schema: |
| 4787 | type: string |
| 4788 | example: "processes" |
| 4789 | - name: timeout |
| 4790 | in: query |
| 4791 | required: false |
| 4792 | description: | |
| 4793 | Maximum time in seconds to wait for function execution before timing out. |
| 4794 | Different functions have different execution times. |
| 4795 | |
| 4796 | **Timeout Guidelines by Function Type:** |
| 4797 | - **Fast queries** (< 1s): processes, mount-points |
| 4798 | Recommended: 10-30 seconds |
| 4799 | - **Medium queries** (1-5s): systemd-list-units, network-connections |
| 4800 | Recommended: 30-60 seconds |
| 4801 | - **Slow operations** (5-30s): docker operations, log queries |
| 4802 | Recommended: 60-300 seconds |
| 4803 | |
| 4804 | **Timeout Behavior:** |
| 4805 | - If execution completes before timeout: Returns results immediately |
| 4806 | - If timeout expires: Function is cancelled and error returned |
| 4807 | - For async functions: Returns transaction ID immediately, timeout applies to overall operation |
| 4808 | |
| 4809 | **Best Practices:** |
| 4810 | - Set conservative timeouts for production systems |
| 4811 | - Consider network latency for remote nodes |
| 4812 | - Monitor timeout errors and adjust accordingly |
| 4813 | schema: |
| 4814 | type: integer |
| 4815 | minimum: 1 |
| 4816 | maximum: 3600 |
| 4817 | default: 60 |
| 4818 | example: 30 |
| 4819 | responses: |
| 4820 | "200": |
| 4821 | description: | |
| 4822 | Function executed successfully and returned results. |
| 4823 | |
| 4824 | The response format depends on the specific function: |
| 4825 | - Most functions return JSON data |
| 4826 | - Some return plain text or formatted output |
| 4827 | - Check Content-Type header |
| 4828 | content: |
| 4829 | application/json: |
| 4830 | schema: |
| 4831 | type: object |
| 4832 | description: Function-specific response data |
| 4833 | examples: |
| 4834 | processes: |
| 4835 | value: |
| 4836 | processes: |
| 4837 | - pid: 1234 |
| 4838 | name: "nginx" |
| 4839 | cpu: 2.5 |
| 4840 | memory: 45678 |
| 4841 | - pid: 5678 |
| 4842 | name: "postgres" |
| 4843 | cpu: 15.3 |
| 4844 | memory: 234567 |
| 4845 | systemd_units: |
| 4846 | value: |
| 4847 | units: |
| 4848 | - name: "nginx.service" |
| 4849 | state: "active" |
| 4850 | substate: "running" |
| 4851 | - name: "postgresql.service" |
| 4852 | state: "active" |
| 4853 | substate: "running" |
| 4854 | text/plain: |
| 4855 | schema: |
| 4856 | type: string |
| 4857 | description: Plain text response from function |
| 4858 | "202": |
| 4859 | description: | |
| 4860 | Function execution started asynchronously. Use the returned transaction ID |
| 4861 | to poll `/api/v3/progress` for status and results. |
| 4862 | content: |
| 4863 | application/json: |
| 4864 | schema: |
| 4865 | type: object |
| 4866 | properties: |
| 4867 | transaction: |
| 4868 | type: string |
| 4869 | format: uuid |
| 4870 | description: Transaction ID for progress tracking |
| 4871 | message: |
| 4872 | type: string |
| 4873 | description: Status message |
| 4874 | "400": |
| 4875 | description: | |
| 4876 | Bad request. Common causes: |
| 4877 | - Missing required `function` parameter |
| 4878 | - Invalid function name format |
| 4879 | - Invalid request body for the function |
| 4880 | "403": |
| 4881 | description: | |
| 4882 | Forbidden. Possible reasons: |
| 4883 | - Function requires higher permissions than current user has |
| 4884 | - Function is disabled in configuration |
| 4885 | - ACL restrictions prevent execution |
| 4886 | "404": |
| 4887 | description: | |
| 4888 | Function not found. The specified function does not exist or is not available on this node. |
| 4889 | "500": |
| 4890 | description: Internal server error during function execution. |
| 4891 | "503": |
| 4892 | description: | |
| 4893 | Service unavailable. Netdata agent is not ready or function execution system is overloaded. |
| 4894 | "504": |
| 4895 | description: Function execution timeout - operation took longer than specified timeout. |
| 4896 | post: |
| 4897 | operationId: function3_post |
| 4898 | tags: |
| 4899 | - functions |
| 4900 | summary: Execute a Netdata function with request body parameters |
| 4901 | description: | |
| 4902 | Same as GET /api/v3/function, but allows passing parameters via request body for functions |
| 4903 | that require complex input or configuration data. |
| 4904 | |
| 4905 | Use this method when: |
| 4906 | - Function requires complex parameters that don't fit in query string |
| 4907 | - Passing sensitive data that shouldn't be in URL |
| 4908 | - Function accepts JSON configuration or structured data |
| 4909 | |
| 4910 | See GET /api/v3/function for complete documentation on functions, timeouts, and responses. |
| 4911 | security: |
| 4912 | - {} |
| 4913 | - bearerAuth: [] |
| 4914 | parameters: |
| 4915 | - name: function |
| 4916 | in: query |
| 4917 | required: true |
| 4918 | description: Name of the function to execute (see GET method for details) |
| 4919 | schema: |
| 4920 | type: string |
| 4921 | example: "processes" |
| 4922 | - name: timeout |
| 4923 | in: query |
| 4924 | required: false |
| 4925 | description: Maximum time in seconds to wait for function execution (see GET method for details) |
| 4926 | schema: |
| 4927 | type: integer |
| 4928 | minimum: 1 |
| 4929 | maximum: 3600 |
| 4930 | default: 60 |
| 4931 | example: 30 |
| 4932 | requestBody: |
| 4933 | description: | |
| 4934 | Optional request body for functions that accept parameters or configuration. |
| 4935 | The format and content depend on the specific function being executed. |
| 4936 | |
| 4937 | **When to Use Request Body:** |
| 4938 | - Functions that accept filtering parameters |
| 4939 | - Functions that need configuration data |
| 4940 | - Functions with complex input requirements |
| 4941 | |
| 4942 | **Common Patterns:** |
| 4943 | - JSON object with function-specific parameters |
| 4944 | - Plain text for simple commands |
| 4945 | - Format specified by function documentation |
| 4946 | |
| 4947 | **Example for logs-query function:** |
| 4948 | ```json |
| 4949 | { |
| 4950 | "after": -3600, |
| 4951 | "before": 0, |
| 4952 | "filter": "error", |
| 4953 | "limit": 100 |
| 4954 | } |
| 4955 | ``` |
| 4956 | required: false |
| 4957 | content: |
| 4958 | application/json: |
| 4959 | schema: |
| 4960 | type: object |
| 4961 | description: Function-specific parameters (varies by function) |
| 4962 | text/plain: |
| 4963 | schema: |
| 4964 | type: string |
| 4965 | description: Plain text parameters for simple functions |
| 4966 | responses: |
| 4967 | "200": |
| 4968 | description: Function executed successfully (see GET method for response details) |
| 4969 | content: |
| 4970 | application/json: |
| 4971 | schema: |
| 4972 | type: object |
| 4973 | text/plain: |
| 4974 | schema: |
| 4975 | type: string |
| 4976 | "202": |
| 4977 | description: Function execution started asynchronously (see GET method for details) |
| 4978 | "400": |
| 4979 | description: Bad request (see GET method for details) |
| 4980 | "403": |
| 4981 | description: Forbidden (see GET method for details) |
| 4982 | "404": |
| 4983 | description: Function not found (see GET method for details) |
| 4984 | "500": |
| 4985 | description: Internal server error (see GET method for details) |
| 4986 | "503": |
| 4987 | description: Service unavailable (see GET method for details) |
| 4988 | "504": |
| 4989 | description: Function execution timeout (see GET method for details) |
| 4990 | /api/v3/functions: |
| 4991 | get: |
| 4992 | operationId: functions3 |
| 4993 | tags: |
| 4994 | - functions |
| 4995 | summary: List available functions across all nodes |
| 4996 | description: | |
| 4997 | Retrieves a catalog of available functions across the monitored infrastructure. |
| 4998 | Functions are plugin-provided operations that extend Netdata's capabilities beyond |
| 4999 | passive metric collection, allowing live queries, diagnostics, and administrative actions. |
| 5000 |
Showing first 5,000 of 11,238 lines.
View raw