--- title: "Metric weights queries" method: POST path: "/api/v3/spaces/{spaceID}/rooms/{roomID}/weights" tags: ["charts"] --- # Metric weights queries `POST /api/v3/spaces/{spaceID}/rooms/{roomID}/weights` ## 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}/weights` - 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 weights (metric correlations) queries. An optional `limit` (alias `cardinality_limit`) returns only the strongest entries; `result_limit` in the response describes the cut. **Scope contexts.** Each `scope.contexts` entry is a literal context ID or an Agent simple pattern: `*` wildcards, `!` negation, and several patterns in one entry separated by `,`, `|`, tab or newline (space is not a separator). Negated entries apply to every included entry; if all entries are negated, all contexts are included. **Routing.** `scope` (not `selectors`) decides which Agent answers for each node. When every entry is a literal, each (node, context) pair is routed on its own, and only nodes that have the context are queried. When any entry is a pattern, each node is routed once and all entries are sent together to its Agent, so overlapping entries (e.g. `system.cpu` and `system.*`) return each dimension once; nodes without matching contexts return no results. **Partial failures.** Nodes that lack the requested contexts, or that have no instance able to answer (capabilities, retention within the window), are omitted. Nodes that fail because of a routing error are listed in `dictionaries.nodes` with an error status (full format only). If no request can be routed, the response is 400 `ErrAllNodesFailed`. ## Path parameters - `spaceID` string, uuid, required - `roomID` string, uuid, required ## Request body - ModelScopeWeightsRequest - `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`. - `cardinality_limit` integer: CardinalityLimit is the same cap as limit and wins when both are supplied. - `limit` integer: Limit caps the response to the strongest entries: dimensions for full results, groups for grouped results. Omitted, null or zero means unlimited. Alias of cardinality_limit, which takes precedence when both are supplied. Full results spanning several nodes are cut on every node before they are merged, so their normalized weights are ranks within the merged returned dimensions rather than within the whole query. - `method` string - `options` string[] - `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 - `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 - ModelScopeWeightsResponse - `agents` ModelAgentSummary[] - `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 - `correlated_dimensions` integer - `db` ModelWeightsDB - `binary_searches` integer - `db_points_per_tier` integer[] - `db_points_read` integer - `db_queries` integer - `query_result_points` integer - `query_time_ms` number - `dictionaries` ModelWeightsDictionaries - `contexts` ModelWeightsContextSummary[] - `ci` integer - `id` string - `units` string - `dimensions` ModelWeightsDimensionSummary[] - `di` integer - `id` string - `instances` ModelWeightsInstanceSummary[] - `id` string - `ii` integer - `nodes` ModelWeightsNodeSummary[] - `mg` string - `nd` string - `ni` integer - `nm` string - `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 - `request` integer[] - `result` integer[] - `result_limit` ModelWeightsResultLimit - `limit` integer: Limit is the effective requested cap after alias resolution. - `returned` integer: Returned is the number of entries in the response, excluding summary rows. - `summary_scope` 'all': SummaryScope is "all": retained instance, context and node rows, total_dimensions_count and correlated_dimensions describe the complete query, not the returned subset. - `total` integer: Total is the number of entries eligible for the cut: correlated dimensions across every node for full results (the population of correlated_dimensions, not total_dimensions_count), merged groups for grouped results. - `truncated` boolean: Truncated is true exactly when total exceeds returned. - `unit` 'dimensions' | 'groups': Unit is "dimensions" for full results or "groups" for grouped results. - `schema` ModelWeightsSchema - `items` ModelWeightsSchemaItem[] - `calculations` object - `dictionary` string - `labels` string[] - `name` string - `type` string - `value` string[] - `type` string - `total_dimensions_count` integer - `v_schema` ModelWeightsSchema - `items` ModelWeightsSchemaItem[] - `calculations` object - `dictionary` string - `labels` string[] - `name` string - `type` string - `value` string[] - `type` string - `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` ModelWeightsView - `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. - `format` string - `time_group` string - `window` 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. ## Other responses - `400`: `"errorCode": "ErrBadRequest"`: when invalid query parameters/req. payload are provided
`"errorCode": "ErrAllNodesFailed"`: when no Agent request could be routed, 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)