docs: add advanced metric query example with time aggregation (#22059)
* docs: add advanced metric query example with time aggregation * docs: expand time_group values table and add aggregation options to api-tokens * docs: fix time_group table scope and add tier:0 caveat to api-tokens * docs: remove link to unpublished skill file from api-tokens.md The :::tip linking to query-netdata-cloud-metrics.md pointed to a page not published on Learn (absent from the docs map). The advanced query section in api-tokens.md is now self-contained with the time_group table, tier:0 caveat, and curl example — no external link needed. * docs: unify tier:0 admonition across query-metrics and api-tokens * docs: restore tier:0 note after time_group_options table Restore the second tier:0 advisory note after the time_group_options table, converting it to a :::important admonition matching the first one. This preserves the original documentation intent of having the tier:0 warning in both the time_group values and time_group_options sections. --------- Co-authored-by: nedi-app[bot] <bot@netdata.cloud> Co-authored-by: nedi-app[bot] <nedi-app[bot]@users.noreply.github.com>
nedi-app[bot] committed
Apr 27, 2026 at 13:11 UTC
98abf4c1e8e352a723e8ebebacce8a259fcceb94
2 files changed
+68
-2
docs/netdata-ai/skills/query-netdata-cloud-metrics.md
+10
-2
@@ -323,7 +323,11 @@ Controls how raw data points within each time interval are combined into one val
323
| `trimmed-mean` | | Mean after trimming outliers. Set trim % in `time_group_options` |
324
| `trimmed-median` | | Median after trimming outliers. Set trim % in `time_group_options` |
325
326
-IMPORTANT: when specifying any time_group except `min`, `max`, `avg`, `sum`, you MUST specify tier=0 to ensure a non-aggregated tier is used.
326
+:::important
327
+
328
+When using `time_group` values other than `min`, `max`, `average`, or `sum`, you MUST specify `"tier": 0` in the `window` object to ensure a non-aggregated storage tier is used. Without it, the query may use a pre-aggregated tier (per-minute or per-hour) where advanced functions like `median`, `stddev`, `ses`, `des`, `percentile`, `countif`, `trimmed-mean`, `trimmed-median`, and `extremes` cannot work correctly.
329
+
330
+:::
331
332
#### time_group_options values
333
@@ -334,7 +338,11 @@ IMPORTANT: when specifying any time_group except `min`, `max`, `avg`, `sum`, you
338
| `trimmed-mean` | Trim percentage | `"5"`, `"10"` |
339
| `trimmed-median` | Trim percentage | `"5"`, `"10"` |
340
337
-IMPORTANT: when specifying any time_group except `min`, `max`, `avg`, `sum`, you MUST specify tier=0 to ensure a non-aggregated tier is used.
341
+:::important
342
+
343
+When using `time_group` values other than `min`, `max`, `average`, or `sum`, you MUST specify `"tier": 0` in the `window` object to ensure a non-aggregated storage tier is used. Without it, the query may use a pre-aggregated tier (per-minute or per-hour) where advanced functions like `median`, `stddev`, `ses`, `des`, `percentile`, `countif`, `trimmed-mean`, `trimmed-median`, and `extremes` cannot work correctly.
344
+
345
+:::
346
347
---
348
docs/netdata-cloud/authentication-and-authorization/api-tokens.md
+58
@@ -76,6 +76,64 @@ curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://ap
76
curl -H 'Accept: application/json' -H "Authorization: Bearer <token>" https://app.netdata.cloud/api/v2/data?contexts=system.cpu&after=-600
77
```
78
79
+**Advanced Metric Queries with Aggregation**
80
+
81
+For more advanced queries with aggregation, use the POST endpoint with a JSON body. This allows you to query metrics with time aggregation (like average values) and control grouping and filtering.
82
+
83
+```console
84
+TOKEN="YOUR_API_TOKEN"
85
+SPACE="YOUR_SPACE_ID"
86
+ROOM="YOUR_ROOM_ID"
87
+
88
+read -r -d '' PAYLOAD <<'EOF'
89
+{
90
+ "scope": {"contexts": ["system.cpu"]},
91
+ "selectors": {"nodes": ["*"], "contexts": ["*"], "instances": ["*"], "dimensions": ["*"], "labels": ["*"], "alerts": ["*"]},
92
+ "window": {"after": -600, "before": 0, "points": 5},
93
+ "aggregations": {
94
+ "metrics": [{"group_by": ["selected"], "aggregation": "sum"}],
95
+ "time": {"time_group": "average"}
96
+ },
97
+ "format": "json2",
98
+ "options": ["jsonwrap", "minify", "unaligned"],
99
+ "timeout": 30000
100
+}
101
+EOF
102
+
103
+curl -s -X POST \
104
+ -H 'Content-Type: application/json' \
105
+ -H "Authorization: Bearer $TOKEN" \
106
+ "https://app.netdata.cloud/api/v3/spaces/$SPACE/rooms/$ROOM/data" \
107
+ -d "$PAYLOAD"
108
+```
109
+
110
+**Time Aggregation Options**
111
+
112
+The `time_group` parameter in `aggregations.time` controls how data points within each time interval are combined:
113
+
114
+| Option | Description | Use Case |
115
+|--------|-------------|----------|
116
+| `average` | Mean value (default) | Average resource consumption over time |
117
+| `min` | Minimum value | Find lowest values in each interval |
118
+| `max` | Maximum value | Find spikes or peaks |
119
+| `sum` | Sum of values | Total volume transferred (counters) |
120
+| `median` | Median value | Robust central tendency |
121
+| `stddev` | Standard deviation | Measure of variability |
122
+| `ses` | Single exponential smoothing | Trend-aware smoothing |
123
+| `des` | Double exponential smoothing | Trend + seasonality smoothing |
124
+| `incremental-sum` | Difference between last and first value | Change over interval |
125
+| `percentile` | Generic percentile (set value in `time_group_options`) | e.g., 95th percentile latency |
126
+| `countif` | Count values matching condition (set condition in `time_group_options`) | e.g., count samples above threshold |
127
+| `trimmed-mean` | Mean after trimming outliers (set trim % in `time_group_options`) | Robust average excluding extremes |
128
+| `trimmed-median` | Median after trimming outliers (set trim % in `time_group_options`) | Robust median excluding extremes |
129
+| `extremes` | Min and max values | Show value range per interval |
130
+
131
+:::important
132
+
133
+When using `time_group` values other than `min`, `max`, `average`, or `sum`, you MUST specify `"tier": 0` in the `window` object to ensure a non-aggregated storage tier is used. Without it, the query may use a pre-aggregated tier (per-minute or per-hour) where advanced functions like `median`, `stddev`, `ses`, `des`, `percentile`, `countif`, `trimmed-mean`, `trimmed-median`, and `extremes` cannot work correctly.
134
+
135
+:::
136
+
137
**Get context information**
138
139
```console