--- title: "Time series data queries" method: POST path: "/api/v3/spaces/{spaceID}/rooms/{roomID}/data" tags: ["charts"] --- # Time series data queries `POST /api/v3/spaces/{spaceID}/rooms/{roomID}/data` ## Request - Base URL: `https://api.netdata.cloud` (the document declares no server; this is the origin it was published from) - URL: `https://api.netdata.cloud/api/v3/spaces/{spaceID}/rooms/{roomID}/data` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Multi-node, multi-context, multi-instance, multi-dimension data queries, with time and metric aggregation. ## Path parameters - `spaceID` string, uuid, required - `roomID` string, uuid, required ## Request body - ModelScopeDataRequest - `aggregations` ModelAggregations - `metrics` ModelMetricsAggregation[] - `aggregation` 'sum' | 'min' | 'max' | 'avg' | 'median' | 'percentage' - `group_by` string[]: 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. - `group_by_label` string[]: A list of the label keys to group by their values. The order of the labels in the list is respected. - `time` ModelTimeAggregation - `time_group` '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': 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. - `time_group_options` 'countif' | 'trimmed-mean' | 'trimmed-median' | 'percentile': When the time grouping function supports additional parameters, this field can be used to pass them to it. - `time_resampling` integer: 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`. - `format` 'json2': The format of the data to be returned. Only `json2` is currently supported by Netdata Cloud. - `options` string[]: Options that affect data generation, more info on each option : https://learn.netdata.cloud/api#/data/dataQuery2. - `scope` ModelScope - `contexts` string[]: The targeted contexts. - `dimensions` string[]: The targeted dimensions. - `instances` string[]: The targeted instances. - `labels` string[]: The targeted labels. - `nodes` string[]: The targeted nodes. - `selectors` ModelSelectors - `alerts` string[]: 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. - `contexts` string[]: 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. - `dimensions` string[]: 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. - `instances` string[]: 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. - `labels` string[]: 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. - `nodes` string[]: 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. - `timeout` integer: Timeout defined in milliseconds. - `window` ModelWindow - `after` integer: 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. - `baseline` ModelWindowSpan - `after` integer: 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. - `before` integer: 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. - `duration` integer - `points` integer: 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. - `before` integer: 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. - `duration` integer - `points` integer: 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. - `tier` integer: Use only the given dbengine tier for executing the query. ## Response `200` OK - ModelScopeDataResponse - `agents` ModelAgentSummary[]: The Agents consulted to compose this response. - `ai` integer: The index of the Agent in the summaries array - `claim_id` string, uuid: The Agent Claim ID - `mg` string, uuid: The Agent Machine GUID - `nd` string, uuid: The Agent Node ID - `nm` string: The Agent Node name - `timings` ModelTimings - `adc_ms` number - `adc_queue_wait_ms` number - `cloud_ms` number - `node_max_ms` number - `output_ms` number - `prep_ms` number - `query_ms` number - `routing_ms` number - `total_ms` number - `api` integer: The API version used. - `db` ModelDB - `dimensions` ModelDBDimensions - `ids` string[]: An array with the dimension ids that uniquely identify the dimensions for this query - `sts` ModelStatsArray - `arc` number[] - `arp` number[] - `avg` number[] - `cnt` number[] - `con` number[] - `max` number[] - `min` number[] - `sum` number[] - `vol` number[] - `units` string[]: An array with the units each dimension has in the database (independent of group-by aggregation that may override the units). - `first_entry` integer: The `min` (earliest) FirstEntry across participating Nodes - `last_entry` integer: The `max` (latest) LastEntry across participating Nodes - `per_tier` ModelTier[]: Aggregated tier information for all participating Nodes - `first_entry` integer - `last_entry` integer - `points` integer - `queries` integer - `tier` integer - `update_every` integer - `tiers` integer: The `max` amount of Database Tiers - `units` integer[]: The Units of the database data - `update_every` integer: The `max` UpdateEvery across participating Nodes - `functions` string[]: A list of the supported Functions - `result` ModelResult - `data` array[]: Data is kept for JSON shape compatibility. Custom marshal/unmarshal store non-null data in timestamps/values and leave this as a non-nil empty slice. - unknown[] - unknown - `labels` string[]: The IDs of the dimensions returned. The first is always `time`. - `point` object: The format of each point returned. - `summary` ModelSummary - `alerts` ModelAlertSummary[]: An array of all the unique alerts running, grouped by alert name - `cl` integer: The count of Clear alerts - `cr` integer: The count of Critical alerts - `nm` string: The Name of the alert can be absent when the counters refer to more than one alert instances. - `ot` integer: The count of Other alerts - `wr` integer: The count of Warning alerts - `contexts` ModelContextSummary[]: Summary of the related Contexts - `al` ModelAlertSummary - `cl` integer: The count of Clear alerts - `cr` integer: The count of Critical alerts - `nm` string: The Name of the alert can be absent when the counters refer to more than one alert instances. - `ot` integer: The count of Other alerts - `wr` integer: The count of Warning alerts - `ds` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `id` string: The Context ID - `is` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `sts` integer[]: Provides global statistics such as `min`, `max`, `sum`, `volume`, `count` and `anomaly-rate-count` - `dimensions` ModelDimensionSummary[]: Summary of the related Dimensions - `ds` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `id` string - `nm` string - `pri` integer - `sts` integer[] - `globals` ModelGlobalSummary - `sts` integer[] - `instances` ModelInstanceSummary[]: Summary of the related Instances - `al` ModelAlertSummary - `cl` integer: The count of Clear alerts - `cr` integer: The count of Critical alerts - `nm` string: The Name of the alert can be absent when the counters refer to more than one alert instances. - `ot` integer: The count of Other alerts - `wr` integer: The count of Warning alerts - `ds` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `id` string - `ni` integer - `nm` string - `sts` integer[] - `labels` ModelLabelSummary[]: Summary of the related Labels - `ds` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `id` string: ID is the label key - `sts` integer[]: Statistics object including `min`, `max`, `avg`, `anomaly-rate` and `contribution-percentage` - `vl` ModelLabelValueSummary[]: The Values are summarizing the label values of the result - `ds` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `id` string: ID is the label value - `sts` integer[]: Statistics object including `min`, `max`, `avg`, `anomaly-rate` and `contribution-percentage` - `nodes` ModelNodeSummary[]: Summary of the related nodes - `al` ModelAlertSummary - `cl` integer: The count of Clear alerts - `cr` integer: The count of Critical alerts - `nm` string: The Name of the alert can be absent when the counters refer to more than one alert instances. - `ot` integer: The count of Other alerts - `wr` integer: The count of Warning alerts - `ds` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `is` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `mg` string, uuid: The Machine GUID - `nd` string, uuid: The Node ID - `ni` integer: The index of the Node in the summaries array - `nm` string: The Node name - `st` ModelNodeStatus - `ai` integer: The index of the Agent that the Node belongs to - `code` integer: The HTTP response code the Agent returned - `ms` number: The required time in milliseconds until the Cloud got back the Agent's response - `msg` string: Any error message the Agent might have returned - `sts` integer[]: Provides global statistics such as `min`, `max`, `sum`, `volume`, `count` and `anomaly-rate-count` - `timings` ModelTimings - `adc_ms` number - `adc_queue_wait_ms` number - `cloud_ms` number - `node_max_ms` number - `output_ms` number - `prep_ms` number - `query_ms` number - `routing_ms` number - `total_ms` number - `totals` ModelTotals - `contexts` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `dimensions` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `instances` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `label_key_values` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `label_keys` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `nodes` ModelItemsCount - `ex` integer: The amount of items that were Excluded - `fl` integer: The amount of items that were not queried successfully - `qr` integer: The amount of items that were queried successfully - `sl` integer: The amount of items that were Selected - `versions` ModelVersions - `alerts_hard_hash` integer: An auto-increment value that reflects the number of changes to the number of alerts. Everytime an alert is added or removed, this number gets incremented. - `alerts_soft_hash` integer: An auto-increment value that reflects the number of alerts transitions. Everytime an alert transitions to a new state, this number gets incremented. - `contexts_hard_hash` integer: An auto-increment value that reflects the number of changes to the number of contexts maintained by the server. Everytime a context is added or removed, this number gets incremented. - `contexts_soft_hash` integer: An auto-increment value that reflects the number of changes to the queue that sends contexts updates to Netdata Cloud. Everytime the contents of a context are updated, this number gets incremented. - `nodes_hard_hash` integer: An auto-increment value that reflects the number of changes to the number of nodes maintained by the server. Everytime a node is added or removed, this number gets incremented. - `routing_hard_hash` integer: An auto-increment value that reflects the number of changes to the streaming routes of the server. - `view` ModelView - `after` integer: The oldest unix epoch timestamp of the data returned - `before` integer: The newest unix epoch timestamp of the data returned - `cardinality` ModelViewCardinality - `cut` number: The largest folded |sum| contribution - the ranking cut. A pointer: agents serialize non-finite doubles as JSON null, and a missing or null cut must be distinguishable from a genuine zero - it voids the certificate instead of silently lowering its bar - `folded` integer: The number of dimensions folded into the 'remaining' aggregate - `chart_type` string: The default chart type of the query - `dimensions` ModelViewDimensions - `aggregated` integer[]: An array with the number of source metrics aggregated into each dimension. - `grouped_by` string[]: An array with the order of the groupings performed. - `ids` string[]: An array with the dimension ids that uniquely identify the dimensions for this query. - `labels` object: The labels associated with each dimension in the query. This object is only available when the `group-by-labels` option is provided. - `names` string[]: An array with the dimension names to be presented to users. Names may be overlapping, but IDs are not. - `priorities` integer[]: 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. - `sts` ModelStatsArray - `arc` number[] - `arp` number[] - `avg` number[] - `cnt` number[] - `con` number[] - `max` number[] - `min` number[] - `sum` number[] - `vol` number[] - `units` string[]: An array with the units each dimension includes. - `max` number: The maximum value of all points included in the result. - `min` number: The minimum value of all points included in the - `partial_data_trimming` ModelPartialDataTrimming - `expected_after` integer - `max_update_every` integer - `trimmed_after` integer - `points` integer: The number of points in result. Available only when `raw` option is provided - `title` string: The title the chart should have - `units` integer[]: The units of the query. - `update_every` integer: The UpdateEvery interval in seconds ## Other responses - `400`: `"errorCode": "ErrBadRequest"`: when invalid query parameters/req. payload are provided
`"errorCode": "ErrBigAgentResponses"`: when Agents return big responses and the caller needs to filter further, reduce the amount of requested `points` or use parents
`"errorCode": "ErrNoEligibleNodeRequested"`: when no eligible nodes were targeted due to space plan restrictions
`"errorCode": "ErrAllNodesFailed"`: when all Agent requests failed, details on every failure are included - `401`: `"errorCode": "ErrUnauthorized"`: when the caller is not authenticated or not authorized to access this resource - `500`: `"errorCode": "ErrInternal"`: when some Internal Server Error has occurred --- [API](https://skmtc.dev/netdata/apis/netdata-cloud-api.md) - [All operations](https://skmtc.dev/netdata/apis/netdata-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/netdata/apis/netdata-cloud-api/revisions/902a6689b462?raw)