Everything related to chart instances - DO NOT USE IN NEW CODE - use contexts instead
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/netdata-charts-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Netdata Cloud Charts API
description: Netdata Cloud API Documentation
version: 0.0.1
contact:
name: Support
url: https://www.netdata.cloud/support
servers:
- url: https://app.netdata.cloud
description: Netdata Cloud
security:
- BearerAuth: []
tags:
- name: charts
paths:
/api/v3/spaces/{spaceID}/rooms/{roomID}/data:
post:
summary: Time series data queries
description: Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation.
operationId: post-scope-data
tags:
- charts
parameters:
- name: spaceID
in: path
required: true
description: The unique identifier of the requested space.
schema:
type: string
format: uuid
- name: roomID
in: path
required: true
description: The unique identifier of the requested room.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ScopeDataRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ScopeDataResponse'
'400':
description: ' `"errorCode": "ErrBadRequest"`: when invalid query parameters/req. payload are provided <br /> `"errorCode": "ErrBigAgentResponses"`: when Agents return big responses and the caller needs to filter further, reduce the amount of requested `points` or use parents <br /> `"errorCode": "ErrNoEligibleNodeRequested"`: when no eligible nodes were targeted due to space plan restrictions <br /> `"errorCode": "ErrAllNodesFailed"`: when all Agent requests failed, details on every failure are included '
content:
application/json:
schema:
$ref: '#/components/schemas/errors.Error'
'401':
description: ' `"errorCode": "ErrUnauthorized"`: when the caller is not authenticated or not authorized to access this resource '
content:
application/json:
schema:
$ref: '#/components/schemas/errors.Error'
'500':
description: ' `"errorCode": "ErrInternal"`: when some Internal Server Error has occurred '
content:
application/json:
schema:
$ref: '#/components/schemas/errors.Error'
components:
schemas:
github_com_netdata_cloud-charts-service_internal_model.Window:
type: object
properties:
after:
description: 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.
type: integer
example: 1745928492
baseline:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.WindowSpan'
before:
description: 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.
type: integer
example: 1745929392
duration:
type: integer
points:
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.
type: integer
example: 100
tier:
description: Use only the given dbengine tier for executing the query.
type: integer
github_com_netdata_cloud-charts-service_internal_model.LabelSummary:
type: object
properties:
ds:
description: Dimensions are th available label keys
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
id:
description: ID is the label key
type: string
sts:
description: Statistics object including `min`, `max`, `avg`, `anomaly-rate` and `contribution-percentage`
type: array
items:
type: integer
vl:
description: The Values are summarizing the label values of the result
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.LabelValueSummary'
github_com_netdata_cloud-charts-service_internal_model.ViewDimensions:
type: object
properties:
aggregated:
description: An array with the number of source metrics aggregated into each dimension.
type: array
items:
type: integer
grouped_by:
description: An array with the order of the groupings performed.
type: array
items:
type: string
ids:
description: An array with the dimension ids that uniquely identify the dimensions for this query.
type: array
items:
type: string
labels:
description: The labels associated with each dimension in the query. This object is only available when the `group-by-labels` option is provided.
type: object
additionalProperties:
type: array
items:
type: array
items:
type: string
names:
description: An array with the dimension names to be presented to users. Names may be overlapping, but IDs are not.
type: array
items:
type: string
priorities:
description: An array with the relative priorities of the dimensions. Numbers may not be sequential or unique. The application is expected to order by this and then by name.
type: array
items:
type: integer
sts:
description: Statistics about the view points for each dimension
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.StatsArray'
units:
description: An array with the units each dimension includes.
type: array
items:
type: string
github_com_netdata_cloud-charts-service_internal_model.DimensionSummary:
type: object
properties:
ds:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
id:
type: string
nm:
type: string
pri:
type: integer
sts:
type: array
items:
type: integer
github_com_netdata_cloud-charts-service_internal_model.ScopeDataResponse:
type: object
properties:
agents:
description: The Agents consulted to compose this response.
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.AgentSummary'
api:
description: The API version used.
type: integer
example: 2
db:
description: Summarized Agent DB related information
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.DB'
functions:
description: A list of the supported Functions
type: array
items:
type: string
result:
description: The composite data query Result
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Result'
summary:
description: Summarized information about nodes, contexts, instances, labels, alerts, and dimensions. The items returned are determined by the scope of the query only, however the statistical data in them are influenced by the filters of the query. Using this information the dashboard allows users to slice and dice the data by filtering and grouping.
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Summary'
timings:
description: Timing information regarding the various phases of the composite query
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Timings'
totals:
description: A summary of the Totals of Nodes, Contexts, Instances, Dimensions and Labels
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Totals'
versions:
description: Hashes that allow the caller to detect important database changes of Netdata Agents.
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Versions'
view:
description: View includes presentation related details
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.View'
github_com_netdata_cloud-charts-service_internal_model.DBDimensions:
type: object
properties:
ids:
description: An array with the dimension ids that uniquely identify the dimensions for this query
type: array
items:
type: string
sts:
description: Statistics of the database dimensions including `max`, `min`, `average`, `sum`, `volume`, `count`, `anomaly-rate-count`, `average-anomaly-rate` and `contribution-percentage`
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.StatsArray'
units:
description: An array with the units each dimension has in the database (independent of group-by aggregation that may override the units).
type: array
items:
type: string
github_com_netdata_cloud-charts-service_internal_model.ScopeDataRequest:
type: object
properties:
aggregations:
description: Aggregations define the time and metric aggregation specs. At last one metric aggregation is required
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Aggregations'
format:
description: The format of the data to be returned. Only `json2` is currently supported by Netdata Cloud.
type: string
default: json2
enum:
- json2
example: json2
options:
description: 'Options that affect data generation, more info on each option : https://learn.netdata.cloud/api#/data/dataQuery2.'
type: array
items:
type: string
enum:
- jsonwrap
- raw
- minify
- debug
- nonzero
- null2zero
- abs
- absolute
- display-absolute
- flip
- reversed
- min2max
- percentage
- seconds
- ms
- milliseconds
- unaligned
- match-ids
- match-names
- anomaly-bit
- jw-anomaly-rates
- details
- group-by-labels
- natural-points
- virtual-points
- selected-tier
- all-dimensions
- label-quotes
- objectrows
- google_json
example:
- jsonwrap
- minify
scope:
description: Scope defines the data that the agent must take into account in order to generate the response. Affects the response data and metadata.
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Scope'
selectors:
description: Selectors act as filters when the agent generates the response, and can only affect response data, not metadata.
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Selectors'
timeout:
description: Timeout defined in milliseconds.
type: integer
default: 10000
example: 12000
window:
description: Window defines the time-frame of a query.
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Window'
github_com_netdata_cloud-charts-service_internal_model.Timings:
type: object
properties:
cloud_ms:
type: number
node_max_ms:
type: number
output_ms:
type: number
prep_ms:
type: number
query_ms:
type: number
routing_ms:
type: number
total_ms:
type: number
github_com_netdata_cloud-charts-service_internal_model.LabelValueSummary:
type: object
properties:
ds:
description: Dimensions are the label key-value pairs
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
id:
description: ID is the label value
type: string
sts:
description: Statistics object including `min`, `max`, `avg`, `anomaly-rate` and `contribution-percentage`
type: array
items:
type: integer
github_com_netdata_cloud-charts-service_internal_model.Result:
type: object
properties:
data:
description: The actual time series data is a 2D array whose contents may vary. The first element should be the timestamp while the rest should be arrays of values for the various dimensions
type: array
items:
type: array
items: {}
labels:
description: The IDs of the dimensions returned. The first is always `time`.
type: array
items:
type: string
point:
description: The format of each point returned.
type: object
additionalProperties:
type: integer
github_com_netdata_cloud-charts-service_internal_model.AgentSummary:
type: object
properties:
ai:
description: The index of the Agent in the summaries array
type: integer
claim_id:
description: The Agent Claim ID
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
mg:
description: The Agent Machine GUID
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
nd:
description: The Agent Node ID
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
nm:
description: The Agent Node name
type: string
example: my_node
timings:
description: Timing information for all the stages included until the final composite response is returned
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Timings'
github_com_netdata_cloud-charts-service_internal_model.Summary:
type: object
properties:
alerts:
description: An array of all the unique alerts running, grouped by alert name
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.AlertSummary'
contexts:
description: Summary of the related Contexts
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ContextSummary'
dimensions:
description: Summary of the related Dimensions
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.DimensionSummary'
globals:
description: Provides global statistics for all entities including the following aggregate values `min`, `max`, `sum`, `volume`, `count` and `anomaly-rate-count`
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.GlobalSummary'
instances:
description: Summary of the related Instances
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.InstanceSummary'
labels:
description: Summary of the related Labels
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.LabelSummary'
nodes:
description: Summary of the related nodes
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.NodeSummary'
github_com_netdata_cloud-charts-service_internal_model.View:
type: object
properties:
after:
description: The oldest unix epoch timestamp of the data returned
type: integer
before:
description: The newest unix epoch timestamp of the data returned
type: integer
chart_type:
description: The default chart type of the query
type: string
dimensions:
description: Detailed information about the chart dimensions included in the response
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ViewDimensions'
max:
description: The maximum value of all points included in the result.
type: number
min:
description: The minimum value of all points included in the
type: number
partial_data_trimming:
description: Holds information related to trimming of the last few points of the result, that was required to remove (increasing) partial data. Trimming is disabled when the `raw` option is given to the query
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.PartialDataTrimming'
points:
description: The number of points in result. Available only when `raw` option is provided
type: integer
title:
description: The title the chart should have
type: string
units:
description: The units of the query.
type: array
items:
type: integer
update_every:
description: The UpdateEvery interval in seconds
type: integer
github_com_netdata_cloud-charts-service_internal_model.AlertSummary:
type: object
properties:
cl:
description: The count of Clear alerts
type: integer
cr:
description: The count of Critical alerts
type: integer
nm:
description: The Name of the alert can be absent when the counters refer to more than one alert instances.
type: string
ot:
description: The count of Other alerts
type: integer
wr:
description: The count of Warning alerts
type: integer
github_com_netdata_cloud-charts-service_internal_model.InstanceSummary:
type: object
properties:
al:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.AlertSummary'
ds:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
id:
type: string
ni:
type: integer
nm:
type: string
sts:
type: array
items:
type: integer
github_com_netdata_cloud-charts-service_internal_model.DB:
type: object
properties:
dimensions:
description: The Database dimensions details
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.DBDimensions'
first_entry:
description: The `min` (earliest) FirstEntry across participating Nodes
type: integer
last_entry:
description: The `max` (latest) LastEntry across participating Nodes
type: integer
per_tier:
description: Aggregated tier information for all participating Nodes
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.Tier'
tiers:
description: The `max` amount of Database Tiers
type: integer
units:
description: The Units of the database data
type: array
items:
type: integer
update_every:
description: The `max` UpdateEvery across participating Nodes
type: integer
github_com_netdata_cloud-charts-service_internal_model.NodeStatus:
type: object
properties:
ai:
description: The index of the Agent that the Node belongs to
type: integer
code:
description: The HTTP response code the Agent returned
type: integer
example: 200
ms:
description: The required time in milliseconds until the Cloud got back the Agent's response
type: number
msg:
description: Any error message the Agent might have returned
type: string
example: timed out
github_com_netdata_cloud-charts-service_internal_model.PartialDataTrimming:
type: object
properties:
expected_after:
type: integer
max_update_every:
type: integer
trimmed_after:
type: integer
github_com_netdata_cloud-charts-service_internal_model.TimeAggregation:
type: object
properties:
time_group:
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.
type: string
default: average
enum:
- min
- max
- avg
- average
- median
- stddev
- sum
- incremental-sum
- ses
- des
- cv
- countif
- percentile
- percentile25
- percentile50
- percentile75
- percentile80
- percentile90
- percentile95
- percentile97
- percentile98
- percentile99
- trimmed-mean
- trimmed-mean1
- trimmed-mean2
- trimmed-mean3
- trimmed-mean5
- trimmed-mean10
- trimmed-mean15
- trimmed-mean20
- trimmed-mean25
- trimmed-median
- trimmed-median1
- trimmed-median2
- trimmed-median3
- trimmed-median5
- trimmed-median10
- trimmed-median15
- trimmed-median20
- trimmed-median25
example: min
time_group_options:
description: When the time grouping function supports additional parameters, this field can be used to pass them to it.
type: string
enum:
- countif
- trimmed-mean
- trimmed-median
- percentile
example: countif
time_resampling:
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 when `time_group` function is `average`.
type: integer
example: 60
github_com_netdata_cloud-charts-service_internal_model.ContextSummary:
type: object
properties:
al:
description: Summary of the Alert counts of the participating nodes by severity
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.AlertSummary'
ds:
description: A breakdown summary of the Dimensions by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
id:
description: The Context ID
type: string
is:
description: A breakdown summary of the Instances by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
sts:
description: Provides global statistics such as `min`, `max`, `sum`, `volume`, `count` and `anomaly-rate-count`
type: array
items:
type: integer
github_com_netdata_cloud-charts-service_internal_model.Tier:
type: object
properties:
first_entry:
type: integer
last_entry:
type: integer
points:
type: integer
queries:
type: integer
tier:
type: integer
update_every:
type: integer
github_com_netdata_cloud-charts-service_internal_model.MetricsAggregation:
type: object
properties:
aggregation:
description: The aggregation function to apply when grouping metrics together.
default: average
enum:
- sum
- min
- max
- avg
- median
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.AggregationMethod'
example: sum
group_by:
description: A list of groupings. All possible values can be combined together, except `selected`. If `selected` is provided, all others are ignored. The order they are placed in the list is currently ignored.
type: array
items:
type: string
enum:
- dimension
- instance
- percentage-of-instance
- label
- node
- context
- units
- selected
example:
- selected
group_by_label:
description: A list of the label keys to group by their values. The order of the labels in the list is respected.
type: array
items:
type: string
example:
- a_label_key
github_com_netdata_cloud-charts-service_internal_model.AggregationMethod:
type: string
enum:
- sum
- min
- max
- avg
- median
- percentage
x-enum-varnames:
- Sum
- Min
- Max
- Avg
- Median
- Pct
github_com_netdata_cloud-charts-service_internal_model.Totals:
type: object
properties:
contexts:
description: A breakdown summary of the Contexts by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
dimensions:
description: A breakdown summary of the Dimensions by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
instances:
description: A breakdown summary of the Instances by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
label_key_values:
description: A breakdown summary of the LabelKeyValues by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
label_keys:
description: A breakdown summary of the LabelKeys by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
nodes:
description: A breakdown summary of the Nodes by outcome and filter
allOf:
- $ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.ItemsCount'
github_com_netdata_cloud-charts-service_internal_model.Aggregations:
type: object
properties:
metrics:
type: array
items:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.MetricsAggregation'
time:
$ref: '#/components/schemas/github_com_netdata_cloud-charts-service_internal_model.TimeAggregation'
github_com_netdata_cloud-charts-service_internal_model.Scope:
type: object
properties:
contexts:
description: The targeted contexts.
type: array
items:
type: string
example:
- disk.space
dimensions:
description: The targeted dimensions.
type: array
items:
type: string
example:
- avail
- used
instances:
description: The targeted instances.
type: array
items:
type: string
example:
- disk_space./@bd498fed-8aa1-440c-a9d6-7c33db570608
labels:
description: The targeted labels.
type: array
items:
type: string
example:
- filesystem:btrfs
- mount_point:/host/var/log
nodes:
description: The targeted nodes.
type: array
items:
type: string
example:
- node_id_1
- node_id_2
github_com_netdata_cloud-charts-service_internal_model.Selectors:
type: object
properties:
alerts:
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.
type: array
items:
type: string
example:
- '*'
contexts:
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.
type: array
items:
type: string
example:
- '*'
dimensions:
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.
type: array
items:
type: string
example:
- sent
- received
instances:
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.
type: array
items:
type: string
example:
- instance1@machine_guid1
- instance2@machine_guid1
- instanceX@machine_guidX
labels:
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, con
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netdata/refs/heads/main/openapi/netdata-charts-api-openapi.yml