{ "opencollection": "1.0.0", "info": { "name": "Netdata agent data API", "version": "v1-rolling" }, "items": [ { "info": { "name": "data", "type": "folder" }, "items": [ { "info": { "name": "Data Query v2", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v2/data", "params": [ { "name": "group_by", "value": "", "type": "query", "description": "A comma separated list of the groupings required.\nAll possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored.\nThe order they are placed in the list is currently ignored.\nThis parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required.\n" }, { "name": "group_by_label", "value": "", "type": "query", "description": "A comma separated list of the label keys to group by their values. The order of the labels in the list is respected.\nThis parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required.\n" }, { "name": "aggregation", "value": "", "type": "query", "description": "The aggregation function to apply when grouping metrics together.\nWhen option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average.\nThis parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required.\n" }, { "name": "scope_nodes", "value": "", "type": "query", "description": "A simple pattern limiting the nodes scope of the query. The scope controls both data and metadata response. The simple pattern is checked against the nodes' machine guid, node id and hostname. The default nodes scope is all nodes for which this Agent has data for. Usually the nodes scope is used to slice the entire dashboard (e.g. the Global Nodes Selector at the Netdata Cloud overview dashboard). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_contexts", "value": "", "type": "query", "description": "A simple pattern limiting the contexts scope of the query. The scope controls both data and metadata response. The default contexts scope is all contexts for which this Agent has data for. Usually the contexts scope is used to slice data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_instances", "value": "", "type": "query", "description": "A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against the instance `id`, the instance `name`, the fully qualified name of the instance `id` and `name`, like `instance@machine_guid`, where `instance` is either its `id` or `name`. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_labels", "value": "", "type": "query", "description": "A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_dimensions", "value": "", "type": "query", "description": "A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "nodes", "value": "", "type": "query", "description": "A simple pattern matching the nodes to be queried. This only controls the data response, not the metadata. The simple pattern is checked against the nodes' machine guid, node id, hostname. The default nodes selector is all the nodes matched by the nodes scope. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "contexts", "value": "", "type": "query", "description": "A simple pattern matching the contexts to be queried. This only controls the data response, not the metadata. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "instances", "value": "", "type": "query", "description": "A simple pattern matching the instances to be queried. The simple pattern is checked against the instance `id`, the instance `name`, the fully qualified name of the instance `id` and `name`, like `instance@machine_guid`, where `instance` is either its `id` or `name`. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "labels", "value": "", "type": "query", "description": "A simple pattern matching the labels to be queried. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by all the above: scope nodes, scope contexts, nodes, contexts and instances). Negative simple patterns should not be used in this filter.\n" }, { "name": "alerts", "value": "", "type": "query", "description": "A simple pattern matching the alerts to be queried. The simple pattern is checked against the `name` of alerts and the combination of `name:status`, when status is one of `CLEAR`, `WARNING`, `CRITICAL`, `REMOVED`, `UNDEFINED`, `UNINITIALIZED`, of all the alerts of all the eligible instances (as filtered by all the above). A negative simple pattern will exclude the instances having the labels matched.\n" }, { "name": "dimensions", "value": "", "type": "query", "description": "A simple patterns matching the dimensions to be queried. The simple pattern is checked against and `id` and the `name` of the dimensions of the eligible instances (as filtered by all the above). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "after", "value": "", "type": "query", "description": "`after` and `before` define the time-frame of a query. `after` can be a negative number of seconds, up to 3 years (-94608000), relative to `before`. If not set, it is usually assumed to be -600. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given.\n" }, { "name": "before", "value": "", "type": "query", "description": "`after` and `before` define the time-frame of a query. `before` can be a negative number of seconds, up to 3 years (-94608000), relative to current clock. If not set, it is assumed to be the current clock time. When `before` is positive, it is assumed to be a unix epoch timestamp. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given.\n" }, { "name": "points", "value": "", "type": "query", "description": "The number of points to be returned. If not given, or it is <= 0, or it is bigger than the points stored in the database for the given duration, all the available collected values for the given duration will be returned. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500).\n" }, { "name": "tier", "value": "", "type": "query", "description": "Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query.\n" }, { "name": "options", "value": "", "type": "query", "description": "Options that affect data generation.\n* `jsonwrap` - Wrap the output in a JSON object with metadata about the query.\n* `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format.\n* `minify` - Remove unnecessary spaces and newlines from the output.\n* `debug` - Provide additional information in `jsonwrap` output to help tracing issues.\n* `nonzero` - Do not return dimensions that all their values are zero, to improve the visual appearance of charts. They will still be returned if all the dimensions are entirely zero.\n* `null2zero` - Replace `null` values with `0`.\n* `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off.\n* `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign.\n* `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest).\n* `min2max` - When flattening multi-dimensional data into a single metric format, use `max - min` instead of `sum`. This is EOL - use `/api/v2` to control aggregation across dimensions.\n* `percentage` - Convert all values into a percentage vs the row total. When enabled, Netdata will query all dimensions, even the ones that have not been selected or are hidden, to find the row total, in order to calculate the percentage of each dimension selected.\n* `seconds` - Output timestamps in seconds instead of dates.\n* `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates.\n* `unaligned` - by default queries are aligned to the the view, so that as time passes past data returned do not change. When a data query will not be used for visualization, `unaligned` can be given to avoid aligning the query time-frame for visual precision.\n* `match-ids`, `match-names`. By default filters match both IDs and names when they are available. Setting either of the two options will disable the other.\n* `anomaly-bit` - query the anomaly information instead of metric values. This is EOL, use `/api/v2` and `json2` format which always returns this information and many more.\n* `jw-anomaly-rates` - return anomaly rates as a separate result set in the same `json` format response. This is EOL, use `/api/v2` and `json2` format which always returns information and many more. \n* `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query.\n* `group-by-labels` - `/api/v2/data` returns in `jsonwrap` flattened labels per output dimension. These are used to identify the instances that have been aggregated into each dimension, making it possible to provide a map, like Netdata does for Kubernetes.\n* `natural-points` - return timestamps as found in the database. The result is again fixed-step, but the query engine attempts to align them with the timestamps found in the database.\n* `virtual-points` - return timestamps independent of the database alignment. This is needed aggregating data across multiple Netdata Agents, to ensure that their outputs do not need to be interpolated to be merged.\n* `selected-tier` - use data exclusively from the selected tier given with the `tier` parameter. This option is set automatically when the `tier` parameter is set.\n* `all-dimensions` - In `/api/v1` `jsonwrap` include metadata for all candidate metrics examined. In `/api/v2` this is standard behavior and no option is needed.\n* `label-quotes` - In `csv` output format, enclose each header label in quotes.\n* `objectrows` - Each row of value should be an object, not an array (only for `json` format).\n* `google_json` - Comply with google JSON/JSONP specs (only for `json` format).\n* `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth.\n* `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones.\n* `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration.\n* `rfc3339` - Return timestamps in RFC3339 format (e.g., \"2023-01-01T00:00:00Z\") instead of Unix timestamps.\n" }, { "name": "time_group", "value": "", "type": "query", "description": "Time aggregation function. If multiple collected values are to be grouped in order to return fewer points, this parameters defines the method of grouping. If the `absolute` option is set, the values are turned positive before applying this calculation.\n" }, { "name": "time_group_options", "value": "", "type": "query", "description": "When the time grouping function supports additional parameters, this field can be used to pass them to it. Currently `countif`, `trimmed-mean`, `trimmed-median` and `percentile` support this. For `countif` the string may start with `<`, `<=`, `<:`, `<>`, `!=`, `>`, `>=`, `>:`. For all others just a number is expected.\n" }, { "name": "time_resampling", "value": "", "type": "query", "description": "For incremental values that are \"per second\", this value is used to resample them to \"per minute` (60) or \"per hour\" (3600). It can only be used in conjunction with group=average.\n" }, { "name": "format", "value": "", "type": "query", "description": "The format of the data to be returned." }, { "name": "cardinality_limit", "value": "", "type": "query", "description": "Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit.\n" }, { "name": "timeout", "value": "", "type": "query", "description": "Specify a timeout value in milliseconds after which the Agent will abort the query and return a 503 error. A value of 0 indicates no timeout.\n" }, { "name": "callback", "value": "", "type": "query", "description": "For JSONP responses, the callback function name.\n" }, { "name": "filename", "value": "", "type": "query", "description": "Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename.\"\n" }, { "name": "tqx", "value": "", "type": "query", "description": "[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.\n" } ] }, "docs": "Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation.\n\n**Security & Access Control:**\n- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token\n- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf\n- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud," }, { "info": { "name": "Data Query v3", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v3/data", "params": [ { "name": "group_by", "value": "", "type": "query", "description": "A comma separated list of the groupings required.\nAll possible values can be combined together, except `selected`. If `selected` is given in the list, all others are ignored.\nThe order they are placed in the list is currently ignored.\nThis parameter is also accepted as `group_by[0]` and `group_by[1]` when multiple grouping passes are required.\n" }, { "name": "group_by_label", "value": "", "type": "query", "description": "A comma separated list of the label keys to group by their values. The order of the labels in the list is respected.\nThis parameter is also accepted as `group_by_label[0]` and `group_by_label[1]` when multiple grouping passes are required.\n" }, { "name": "aggregation", "value": "", "type": "query", "description": "The aggregation function to apply when grouping metrics together.\nWhen option `raw` is given, `average` and `avg` behave like `sum` and the caller is expected to calculate the average.\nThis parameter is also accepted as `aggregation[0]` and `aggregation[1]` when multiple grouping passes are required.\n" }, { "name": "scope_nodes", "value": "", "type": "query", "description": "A simple pattern limiting the nodes scope of the query. The scope controls both data and metadata response. The simple pattern is checked against the nodes' machine guid, node id and hostname. The default nodes scope is all nodes for which this Agent has data for. Usually the nodes scope is used to slice the entire dashboard (e.g. the Global Nodes Selector at the Netdata Cloud overview dashboard). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_contexts", "value": "", "type": "query", "description": "A simple pattern limiting the contexts scope of the query. The scope controls both data and metadata response. The default contexts scope is all contexts for which this Agent has data for. Usually the contexts scope is used to slice data on the dashboard (e.g. each context based chart has its own contexts scope, limiting the chart to all the instances of the selected context). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_instances", "value": "", "type": "query", "description": "A simple pattern limiting the instances scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against the instance `id`, the instance `name`, the fully qualified name of the instance `id` and `name`, like `instance@machine_guid`, where `instance` is either its `id` or `name`. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_labels", "value": "", "type": "query", "description": "A simple pattern limiting the labels scope of the query. The scope controls both data and metadata response. This limits which instances are even considered for the query based on their labels. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by scope nodes, scope contexts, and scope instances). Only instances having labels that match this pattern will be included in the query. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "scope_dimensions", "value": "", "type": "query", "description": "A simple pattern limiting the dimensions scope of the query. The scope controls both data and metadata response. This limits which dimensions are even considered for the query, including their visibility in the query response metadata. The simple pattern is checked against both the dimension `id` and `name`. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "nodes", "value": "", "type": "query", "description": "A simple pattern matching the nodes to be queried. This only controls the data response, not the metadata. The simple pattern is checked against the nodes' machine guid, node id, hostname. The default nodes selector is all the nodes matched by the nodes scope. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "contexts", "value": "", "type": "query", "description": "A simple pattern matching the contexts to be queried. This only controls the data response, not the metadata. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "instances", "value": "", "type": "query", "description": "A simple pattern matching the instances to be queried. The simple pattern is checked against the instance `id`, the instance `name`, the fully qualified name of the instance `id` and `name`, like `instance@machine_guid`, where `instance` is either its `id` or `name`. Both positive and negative simple pattern expressions are supported.\n" }, { "name": "labels", "value": "", "type": "query", "description": "A simple pattern matching the labels to be queried. The simple pattern is checked against `name:value` of all the labels of all the eligible instances (as filtered by all the above: scope nodes, scope contexts, nodes, contexts and instances). Negative simple patterns should not be used in this filter.\n" }, { "name": "alerts", "value": "", "type": "query", "description": "A simple pattern matching the alerts to be queried. The simple pattern is checked against the `name` of alerts and the combination of `name:status`, when status is one of `CLEAR`, `WARNING`, `CRITICAL`, `REMOVED`, `UNDEFINED`, `UNINITIALIZED`, of all the alerts of all the eligible instances (as filtered by all the above). A negative simple pattern will exclude the instances having the labels matched.\n" }, { "name": "dimensions", "value": "", "type": "query", "description": "A simple patterns matching the dimensions to be queried. The simple pattern is checked against and `id` and the `name` of the dimensions of the eligible instances (as filtered by all the above). Both positive and negative simple pattern expressions are supported.\n" }, { "name": "after", "value": "", "type": "query", "description": "`after` and `before` define the time-frame of a query. `after` can be a negative number of seconds, up to 3 years (-94608000), relative to `before`. If not set, it is usually assumed to be -600. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given.\n" }, { "name": "before", "value": "", "type": "query", "description": "`after` and `before` define the time-frame of a query. `before` can be a negative number of seconds, up to 3 years (-94608000), relative to current clock. If not set, it is assumed to be the current clock time. When `before` is positive, it is assumed to be a unix epoch timestamp. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given.\n" }, { "name": "points", "value": "", "type": "query", "description": "The number of points to be returned. If not given, or it is <= 0, or it is bigger than the points stored in the database for the given duration, all the available collected values for the given duration will be returned. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500).\n" }, { "name": "tier", "value": "", "type": "query", "description": "Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query.\n" }, { "name": "options", "value": "", "type": "query", "description": "Options that affect data generation.\n* `jsonwrap` - Wrap the output in a JSON object with metadata about the query.\n* `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format.\n* `minify` - Remove unnecessary spaces and newlines from the output.\n* `debug` - Provide additional information in `jsonwrap` output to help tracing issues.\n* `nonzero` - Do not return dimensions that all their values are zero, to improve the visual appearance of charts. They will still be returned if all the dimensions are entirely zero.\n* `null2zero` - Replace `null` values with `0`.\n* `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off.\n* `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign.\n* `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest).\n* `min2max` - When flattening multi-dimensional data into a single metric format, use `max - min` instead of `sum`. This is EOL - use `/api/v2` to control aggregation across dimensions.\n* `percentage` - Convert all values into a percentage vs the row total. When enabled, Netdata will query all dimensions, even the ones that have not been selected or are hidden, to find the row total, in order to calculate the percentage of each dimension selected.\n* `seconds` - Output timestamps in seconds instead of dates.\n* `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates.\n* `unaligned` - by default queries are aligned to the the view, so that as time passes past data returned do not change. When a data query will not be used for visualization, `unaligned` can be given to avoid aligning the query time-frame for visual precision.\n* `match-ids`, `match-names`. By default filters match both IDs and names when they are available. Setting either of the two options will disable the other.\n* `anomaly-bit` - query the anomaly information instead of metric values. This is EOL, use `/api/v2` and `json2` format which always returns this information and many more.\n* `jw-anomaly-rates` - return anomaly rates as a separate result set in the same `json` format response. This is EOL, use `/api/v2` and `json2` format which always returns information and many more. \n* `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query.\n* `group-by-labels` - `/api/v2/data` returns in `jsonwrap` flattened labels per output dimension. These are used to identify the instances that have been aggregated into each dimension, making it possible to provide a map, like Netdata does for Kubernetes.\n* `natural-points` - return timestamps as found in the database. The result is again fixed-step, but the query engine attempts to align them with the timestamps found in the database.\n* `virtual-points` - return timestamps independent of the database alignment. This is needed aggregating data across multiple Netdata Agents, to ensure that their outputs do not need to be interpolated to be merged.\n* `selected-tier` - use data exclusively from the selected tier given with the `tier` parameter. This option is set automatically when the `tier` parameter is set.\n* `all-dimensions` - In `/api/v1` `jsonwrap` include metadata for all candidate metrics examined. In `/api/v2` this is standard behavior and no option is needed.\n* `label-quotes` - In `csv` output format, enclose each header label in quotes.\n* `objectrows` - Each row of value should be an object, not an array (only for `json` format).\n* `google_json` - Comply with google JSON/JSONP specs (only for `json` format).\n* `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth.\n* `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones.\n* `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration.\n* `rfc3339` - Return timestamps in RFC3339 format (e.g., \"2023-01-01T00:00:00Z\") instead of Unix timestamps.\n" }, { "name": "time_group", "value": "", "type": "query", "description": "Time aggregation function. If multiple collected values are to be grouped in order to return fewer points, this parameters defines the method of grouping. If the `absolute` option is set, the values are turned positive before applying this calculation.\n" }, { "name": "time_group_options", "value": "", "type": "query", "description": "When the time grouping function supports additional parameters, this field can be used to pass them to it. Currently `countif`, `trimmed-mean`, `trimmed-median` and `percentile` support this. For `countif` the string may start with `<`, `<=`, `<:`, `<>`, `!=`, `>`, `>=`, `>:`. For all others just a number is expected.\n" }, { "name": "time_resampling", "value": "", "type": "query", "description": "For incremental values that are \"per second\", this value is used to resample them to \"per minute` (60) or \"per hour\" (3600). It can only be used in conjunction with group=average.\n" }, { "name": "format", "value": "", "type": "query", "description": "The format of the data to be returned." }, { "name": "cardinality_limit", "value": "", "type": "query", "description": "Limits the number of unique items (contexts, instances, dimensions) returned in the query result. This is useful for preventing excessive memory usage and response sizes when queries match a large number of metrics. The query engine will return the most relevant items up to this limit.\n" }, { "name": "timeout", "value": "", "type": "query", "description": "Specify a timeout value in milliseconds after which the Agent will abort the query and return a 503 error. A value of 0 indicates no timeout.\n" }, { "name": "callback", "value": "", "type": "query", "description": "For JSONP responses, the callback function name.\n" }, { "name": "filename", "value": "", "type": "query", "description": "Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename.\"\n" }, { "name": "tqx", "value": "", "type": "query", "description": "[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.\n" } ] }, "docs": "Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation.\n\n**Security & Access Control:**\n- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token\n- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf\n- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud," }, { "info": { "name": "Data Query v1 - Single node, single chart or context queries. without group-by.", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v1/data", "params": [ { "name": "chart", "value": "", "type": "query", "description": "The id of the chart as returned by the `/api/v1/charts` call." }, { "name": "context", "value": "", "type": "query", "description": "The context of the chart as returned by the /charts call." }, { "name": "dimension", "value": "", "type": "query", "description": "Zero, one or more dimension ids or names, as returned by the /chart call, separated with comma or pipe. Netdata simple patterns are supported." }, { "name": "chart_label_key", "value": "", "type": "query", "description": "Specify the chart label keys that need to match for context queries as comma separated values. At least one matching key is needed to match the corresponding chart.\n" }, { "name": "chart_labels_filter", "value": "", "type": "query", "description": "Specify the chart label keys and values to match for context queries. All keys/values need to match for the chart to be included in the query. The labels are specified as key1:value1,key2:value2\n" }, { "name": "after", "value": "", "type": "query", "description": "`after` and `before` define the time-frame of a query. `after` can be a negative number of seconds, up to 3 years (-94608000), relative to `before`. If not set, it is usually assumed to be -600. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given.\n" }, { "name": "before", "value": "", "type": "query", "description": "`after` and `before` define the time-frame of a query. `before` can be a negative number of seconds, up to 3 years (-94608000), relative to current clock. If not set, it is assumed to be the current clock time. When `before` is positive, it is assumed to be a unix epoch timestamp. When non-data endpoints support the `after` and `before`, they use the time-frame to limit their response for objects having data retention within the time-frame given.\n" }, { "name": "points", "value": "", "type": "query", "description": "The number of points to be returned. If not given, or it is <= 0, or it is bigger than the points stored in the database for the given duration, all the available collected values for the given duration will be returned. For `weights` endpoints that do statistical analysis, the `points` define the detail of this analysis (the default is 500).\n" }, { "name": "tier", "value": "", "type": "query", "description": "Use only the given dbengine tier for executing the query. Setting this parameters automatically sets the option `selected-tier` for the query.\n" }, { "name": "options", "value": "", "type": "query", "description": "Options that affect data generation.\n* `jsonwrap` - Wrap the output in a JSON object with metadata about the query.\n* `raw` - change the output so that it is aggregatable across multiple such queries. Supported by `/api/v2` data queries and `json2` format.\n* `minify` - Remove unnecessary spaces and newlines from the output.\n* `debug` - Provide additional information in `jsonwrap` output to help tracing issues.\n* `nonzero` - Do not return dimensions that all their values are zero, to improve the visual appearance of charts. They will still be returned if all the dimensions are entirely zero.\n* `null2zero` - Replace `null` values with `0`.\n* `absolute` or `abs` - Traditionally Netdata returns select dimensions negative to improve visual appearance. This option turns this feature off.\n* `display-absolute` - Only used by badges, to do color calculation using the signed value, but render the value without a sign.\n* `flip` or `reversed` - Order the timestamps array in reverse order (newest to oldest).\n* `min2max` - When flattening multi-dimensional data into a single metric format, use `max - min` instead of `sum`. This is EOL - use `/api/v2` to control aggregation across dimensions.\n* `percentage` - Convert all values into a percentage vs the row total. When enabled, Netdata will query all dimensions, even the ones that have not been selected or are hidden, to find the row total, in order to calculate the percentage of each dimension selected.\n* `seconds` - Output timestamps in seconds instead of dates.\n* `milliseconds` or `ms` - Output timestamps in milliseconds instead of dates.\n* `unaligned` - by default queries are aligned to the the view, so that as time passes past data returned do not change. When a data query will not be used for visualization, `unaligned` can be given to avoid aligning the query time-frame for visual precision.\n* `match-ids`, `match-names`. By default filters match both IDs and names when they are available. Setting either of the two options will disable the other.\n* `anomaly-bit` - query the anomaly information instead of metric values. This is EOL, use `/api/v2` and `json2` format which always returns this information and many more.\n* `jw-anomaly-rates` - return anomaly rates as a separate result set in the same `json` format response. This is EOL, use `/api/v2` and `json2` format which always returns information and many more. \n* `details` - `/api/v2/data` returns in `jsonwrap` the full tree of dimensions that have been matched by the query.\n* `group-by-labels` - `/api/v2/data` returns in `jsonwrap` flattened labels per output dimension. These are used to identify the instances that have been aggregated into each dimension, making it possible to provide a map, like Netdata does for Kubernetes.\n* `natural-points` - return timestamps as found in the database. The result is again fixed-step, but the query engine attempts to align them with the timestamps found in the database.\n* `virtual-points` - return timestamps independent of the database alignment. This is needed aggregating data across multiple Netdata Agents, to ensure that their outputs do not need to be interpolated to be merged.\n* `selected-tier` - use data exclusively from the selected tier given with the `tier` parameter. This option is set automatically when the `tier` parameter is set.\n* `all-dimensions` - In `/api/v1` `jsonwrap` include metadata for all candidate metrics examined. In `/api/v2` this is standard behavior and no option is needed.\n* `label-quotes` - In `csv` output format, enclose each header label in quotes.\n* `objectrows` - Each row of value should be an object, not an array (only for `json` format).\n* `google_json` - Comply with google JSON/JSONP specs (only for `json` format).\n* `minimal-stats` or `minimal` - Reduce the amount of statistics returned in `jsonwrap` format to save bandwidth.\n* `long-json-keys` or `long-keys` - Use descriptive key names in JSON output instead of abbreviated ones.\n* `mcp-info` - Include additional metadata useful for the Model Context Protocol (MCP) integration.\n* `rfc3339` - Return timestamps in RFC3339 format (e.g., \"2023-01-01T00:00:00Z\") instead of Unix timestamps.\n" }, { "name": "format", "value": "", "type": "query", "description": "The format of the data to be returned." }, { "name": "group", "value": "", "type": "query", "description": "Time aggregation function. If multiple collected values are to be grouped in order to return fewer points, this parameters defines the method of grouping. If the `absolute` option is set, the values are turned positive before applying this calculation.\n" }, { "name": "group_options", "value": "", "type": "query", "description": "When the time grouping function supports additional parameters, this field can be used to pass them to it. Currently `countif`, `trimmed-mean`, `trimmed-median` and `percentile` support this. For `countif` the string may start with `<`, `<=`, `<:`, `<>`, `!=`, `>`, `>=`, `>:`. For all others just a number is expected.\n" }, { "name": "gtime", "value": "", "type": "query", "description": "The grouping number of seconds. This is used in conjunction with group=average to change the units of metrics (ie when the data is per-second, setting gtime=60 will turn them to per-minute).\n" }, { "name": "timeout", "value": "", "type": "query", "description": "Specify a timeout value in milliseconds after which the Agent will abort the query and return a 503 error. A value of 0 indicates no timeout.\n" }, { "name": "callback", "value": "", "type": "query", "description": "For JSONP responses, the callback function name.\n" }, { "name": "filename", "value": "", "type": "query", "description": "Add `Content-Disposition: attachment; filename=` header to the response, that will instruct the browser to save the response with the given filename.\"\n" }, { "name": "tqx", "value": "", "type": "query", "description": "[Google Visualization API](https://developers.google.com/chart/interactive/docs/dev/implementing_data_source?hl=en) formatted parameter.\n" } ] }, "docs": "Query metric data of a chart or context of a node and return a dataset having time-series data for all dimensions available.\nFor group-by functionality, use `/api/v2/data`.\nAt least a `chart` or a `context` have to be given for the data query to be executed.\n\n**Security & Access Control:**\n- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`" }, { "info": { "name": "All Metrics v1 - Fetch latest value for all metrics", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v1/allmetrics", "params": [ { "name": "format", "value": "", "type": "query", "description": "The format of the response to be returned." }, { "name": "filter", "value": "", "type": "query", "description": "Allows to filter charts out using simple patterns." }, { "name": "variables", "value": "", "type": "query", "description": "When enabled, netdata will expose various system configuration variables.\n" }, { "name": "timestamps", "value": "", "type": "query", "description": "Enable or disable timestamps in prometheus output.\n" }, { "name": "names", "value": "", "type": "query", "description": "When enabled netdata will report dimension names. When disabled netdata will report dimension IDs. The default is controlled in netdata.conf.\n" }, { "name": "oldunits", "value": "", "type": "query", "description": "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.\n" }, { "name": "hideunits", "value": "", "type": "query", "description": "When enabled, netdata will not include the units in the metric names, for the default `source=average`.\n" }, { "name": "server", "value": "", "type": "query", "description": "Set a distinct name of the client querying prometheus metrics. Netdata will use the client IP if this is not set.\n" }, { "name": "prefix", "value": "", "type": "query", "description": "Prefix all prometheus metrics with this string.\n" }, { "name": "data", "value": "", "type": "query", "description": "Select the prometheus response data source. There is a setting in netdata.conf for the default.\n" } ] }, "docs": "The `allmetrics` endpoint returns the latest value of all metrics maintained for a netdata node.\n\n**Security & Access Control:**\n- 📊 **Public Data API** - Bearer token optional, IP-based ACL restrictions apply\n- **Default Access:** Public (no authentication required)\n- **Bearer Protection:** When enabled via `/api/v3/bearer_protection`, requires bearer token\n- **IP Restrictions:** Subject to `allow dashboard from` in netdata.conf\n- **Access Methods:** Direct HTTP/HTTPS, Netdata Cloud, external " }, { "info": { "name": "All Metrics v3 - Export all metrics in various formats - Latest API", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v3/allmetrics", "params": [ { "name": "format", "value": "", "type": "query", "description": "The export format for the metrics. Required parameter.\n\n**Formats:**\n- `shell`: Bash variables (default) - Exports as NETDATA_CHARTNAME_DIMENSIONNAME=\"value\"\n- `prometheus`: Prometheus format (single host) - Compatible with Prometheus scraping\n- `prometheus_all_hosts`: Prometheus format (all hosts) - Includes metrics from child nodes with host labels\n- `json`: JSON format - Full metadata including chart names, families, contexts, units, and timestamps\n\n**Format Details:**\n- Shell format includes alarm status variables (NETDATA_ALARM_CHART_ALARM_STATUS, NETDATA_ALARM_CHART_ALARM_VALUE)\n- Prometheus formats respect Prometheus metric naming conventions\n- JSON format provides complete chart and dimension information\n" }, { "name": "filter", "value": "", "type": "query", "description": "Simple pattern filter to include only specific charts. Uses Netdata simple pattern matching.\n\n**Pattern Syntax:**\n- Exact match: `system.cpu`\n- Wildcard: `system.*` (all system charts)\n- Multiple patterns: `system.* disk.*` (space-separated)\n- Negation: `!system.cpu` (exclude specific chart)\n\nWhen not specified, all charts are exported.\n\n**Examples:**\n- `system.*` - Export only system charts\n- `disk.* net.*` - Export disk and network charts\n- `* !*.mdstat` - Export all except mdstat charts\n" }, { "name": "variables", "value": "", "type": "query", "description": "**Prometheus format only**: Include or exclude system configuration variables in the output.\n\nWhen enabled (yes/1/true), Netdata exposes various system configuration variables as Prometheus metrics. This includes:\n- Netdata configuration parameters\n- System environment information\n- Collection plugin states\n\nNote: Only affects Prometheus format output. Ignored for shell and json formats.\n" }, { "name": "timestamps", "value": "", "type": "query", "description": "**Prometheus format only**: Include or exclude timestamps in Prometheus metrics.\n\nWhen enabled (default), each metric includes a timestamp of when it was collected.\nWhen disabled, metrics are exported without timestamps (Prometheus will use scrape time).\n\nNote: Only affects Prometheus format output. Ignored for shell and json formats.\n" }, { "name": "names", "value": "", "type": "query", "description": "**Prometheus format only**: Use dimension names vs IDs in metric names.\n\nWhen enabled (default), Prometheus metrics use human-readable dimension names.\nWhen disabled, metrics use dimension IDs (which never change).\n\n**Example:**\n- names=yes: `netdata_system_cpu_percentage_average{dimension=\"user\"}`\n- names=no: `netdata_system_cpu_percentage_average{dimension=\"user\"}`\n\nThe default is controlled by the global Netdata configuration. This parameter allows per-request override.\n\nNote: Only affects Prometheus format output.\n" }, { "name": "oldunits", "value": "", "type": "query", "description": "**Prometheus format only**: Use legacy unit naming conventions (pre-1.12 format).\n\nWhen enabled, metric names for `source=average` use the old unit naming conventions as they appeared before Netdata version 1.12.\n\nThis is provided for backward compatibility with existing Prometheus configurations.\n\nNote: Only affects Prometheus format with source=average.\n" }, { "name": "hideunits", "value": "", "type": "query", "description": "**Prometheus format only**: Exclude units from metric names for source=average.\n\nWhen enabled, units are not included in the Prometheus metric names for the default `source=average` data.\n\n**Example:**\n- hideunits=no: `netdata_system_cpu_percentage_average`\n- hideunits=yes: `netdata_system_cpu_average`\n\nNote: Only affects Prometheus format with source=average.\n" }, { "name": "server", "value": "", "type": "query", "description": "**Prometheus format only**: Set a custom identifier for the client scraping the metrics.\n\nThis parameter is used to identify the client in Prometheus metric labels. If not specified, Netdata uses the client's IP address.\n\nUseful when multiple Prometheus instances scrape the same Netdata agent, or when scraping through a proxy.\n\n**Example:** `server=prometheus-prod-1`\n\nNote: Only affects Prometheus format output. This value appears in metric labels to distinguish scraping sources.\n" }, { "name": "prefix", "value": "", "type": "query", "description": "**Prometheus format only**: Prefix all Prometheus metric names with a custom string.\n\nUseful for namespacing metrics when aggregating from multiple sources or to comply with organizational metric naming conventions.\n\n**Example:** `prefix=mycompany_` produces metrics like `mycompany_system_cpu_percentage_average`\n\nThe default prefix is controlled by the global Netdata configuration. This parameter allows per-request override.\n\nNote: Only affects Prometheus format output.\n" }, { "name": "data", "value": "", "type": "query", "description": "**Prometheus format only**: Select the data source/aggregation method for Prometheus metrics.\n\n**Options:**\n- `as-collected`: Raw values as collected by data collection plugins (no aggregation)\n- `average`: Average values over the collection interval (default)\n- `sum`: Sum of values over the collection interval\n\nThe `as-collected` source provides the most recent raw sample, while `average` and `sum` provide values aggregated over the chart's update interval.\n\nThe default is controlled by the global Netdata exporting configuration. This parameter allows per-request override.\n\n**Use Cases:**\n- `as-collected`: For counter metrics that Prometheus will rate()\n- `average`: For gauge metrics showing typical values\n- `sum`: For accumulating metrics\n\nAliases: `source`, `data source`, `data-source`, `data_source`, `datasource`\n\nNote: Only affects Prometheus format output.\n" } ] }, "docs": "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.\n\nThis is the latest version (v3) of the allmetrics API. It provides the same functionality as v1 but may include additional features in the future.\n\n**Supported Export Formats:**\n- **shell**: Bash-compatible variable assignments for scripting (NETDATA_CHARTNAME_DIMENSIONNAME=\"value\")\n- **prometheus**: Prometh" }, { "info": { "name": "[DEPRECATED] Get a chart variable value", "type": "http" }, "http": { "method": "GET", "url": "https://registry.my-netdata.io/api/v1/variable", "params": [ { "name": "chart", "value": "system.cpu", "type": "query", "description": "Chart ID for which to retrieve the variable. This is the full chart ID as shown in the dashboard.\n\n**Examples:**\n- `system.cpu` - System CPU usage chart\n- `disk.sda.io` - Disk I/O for sda\n- `nginx_local.connections` - Nginx connections\n" }, { "name": "variable", "value": "used", "type": "query", "description": "Variable name to retrieve. Each chart has different variables available depending on its configuration and alert definitions.\n\n**Common Variables:**\n- `used` - Used value (for utilization charts)\n- `free` - Free value (for utilization charts)\n- `value` - Current value\n- `avg` - Average value\n- `sum` - Sum of all dimensions\n- Custom variable names defined in alert configurations\n" } ] }, "docs": "**[DEPRECATED - Use `/api/v3/variable` instead]**\n\n**Chart Variable Retrieval**\n\nThis endpoint returns the current value of a chart variable. Variables are values computed by Netdata that can be used in alert expressions and calculations. Each chart can have multiple variables representing different aspects of its data.\n\n**Common Variables:**\n- Calculated values (averages, sums, percentages)\n- Threshold values used in alerts\n- State information (counts, flags)\n- Time-based values (last update, c" } ] } ], "bundled": true }