Query Netdata Cloud via REST API
This skill teaches end-users (and AI assistants helping them) how to
construct REST API queries against Netdata Cloud
(https://app.netdata.cloud) using a long-lived API token.
It is split into one shared overview (this file) and four
domain-specific guides. Each guide is self-contained and includes
runnable curl commands.
Canonical reference docs (in this repo)
For the query protocol details these guides build on, read the authoritative
sources directly:
| File |
What it covers |
<repo>/src/plugins.d/FUNCTION_UI_REFERENCE.md |
Functions v3 protocol -- envelope, simple-table vs log-explorer, facets, histograms, charts, field types, pagination, delta mode, PLAY mode, error handling. The single most important reference for any Function work. |
<repo>/src/plugins.d/FUNCTION_UI_SCHEMA.json |
JSON Schema for validating Function responses |
<repo>/src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json |
JSON Schema for validating production topology payloads |
<repo>/src/plugins.d/DYNCFG.md |
External-plugin DynCfg protocol (go.d.plugin and other external collectors) |
<repo>/src/daemon/dyncfg/README.md |
Internal DynCfg (high-level and low-level APIs, command enums, lifecycle) |
For querying agents directly (without going through Cloud) -- including
auto-minting agent bearer tokens from a Cloud token -- see the sibling
skill query-netdata-agents.
Mandatory Requirements (READ FIRST)
If you analyze, you author a how-to. When asked a concrete
question about a Netdata environment that isn't already covered
by an existing how-to under how-tos/, you MUST
author a new how-to in this directory and add it to
how-tos/INDEX.md BEFORE completing the
task. The catalog is meant to be live -- the next assistant
should not redo the same analysis from scratch. Keep this
catalog operator-facing: recipes here should explain how to fetch
or use Cloud data. Developer contract validation for collectors,
topology producers, schemas, fixtures, UI adapters, or aggregator
handoffs belongs in the relevant project developer skill, not in
this public skill.
Use the token-safe wrappers. Every example in this skill
uses agents_query_cloud (and friends) from
../query-netdata-agents/scripts/_lib.sh. Never paste raw
Authorization: Bearer $TOKEN curl commands -- that exposes
the cloud token to the assistant. The wrappers handle auth
internally and emit only the response body to stdout.
Provide actionable instructions. You don't run queries for
users. Your role is to teach them. Every response that proposes a
query must end in a complete, runnable command (wrapper-based,
not raw curl).
Never ask for credentials. Do not request API tokens, Space
IDs, or Room IDs. Use placeholders (YOUR_API_TOKEN,
YOUR_SPACE_ID, YOUR_ROOM_ID) at the top of your curl examples
so the user fills them in locally.
Always include a runnable curl command. A response without a
complete curl -X METHOD ... -H ... -d '...' block is incomplete.
Use a heredoc for the JSON body so the user does not have to
escape quotes:
read -r -d '' PAYLOAD <<'EOF'
{ "scope": { "contexts": ["system.cpu"] }, ... }
EOF
Domain-specific gotchas live in the per-domain guide. For
metrics, the most important is scope.contexts MUST be set. See
the per-domain guide for the rest.
Prerequisites
Three things are needed for any query:
1. API Token
- Login to app.netdata.cloud
- Click the user icon (lower-left corner -- tooltip shows your name)
- Select User Settings
- Open the API Tokens tab
- Click the [+] button (top-left)
- Pick a scope, enter a description, click Create
- Copy the token immediately -- it is shown once.
Recommended scope: scope:all (full access) or scope:grafana-plugin
(read-only data endpoints).
2. Space ID
- In the dashboard, click the gear icon below the spaces list
(tooltip: "Space Settings")
- In the Info tab, copy the Space Id.
3. Room ID
- In Space Settings, open the Rooms tab
- Click the > icon at the right of the row (tooltip: "Room
Settings")
- In the Room tab, copy the Room Id.
Authentication
All endpoints accept the cloud token as an HTTP Authorization
header:
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json (for POST endpoints)
GET endpoints do not require the Content-Type header but accept it.
Discovery Endpoints (used by every domain)
These endpoints enumerate what the cloud token can see. Use them when
you don't know the Space ID, Room ID, or node UUID up front.
| Endpoint |
Method |
Purpose |
/api/v2/accounts/me |
GET |
Confirm the token works; returns the user identity. |
/api/v2/spaces |
GET |
List spaces visible to this token. |
/api/v2/spaces/{spaceID}/rooms |
GET |
List rooms in a space. |
/api/v3/spaces/{spaceID}/rooms/{roomID}/nodes |
POST {} |
List nodes in a room with full metadata. |
Example: list spaces
TOKEN="YOUR_API_TOKEN"
curl -sS \
-H "Authorization: Bearer $TOKEN" \
"https://app.netdata.cloud/api/v2/spaces"
Each space record contains id, slug, name, permissions[], and
metadata. Match by name or slug to find the space you want.
Example: list rooms in a space
TOKEN="YOUR_API_TOKEN"
SPACE="YOUR_SPACE_ID"
curl -sS \
-H "Authorization: Bearer $TOKEN" \
"https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms"
Example: list nodes in a room
TOKEN="YOUR_API_TOKEN"
SPACE="YOUR_SPACE_ID"
ROOM="YOUR_ROOM_ID"
curl -sS -X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $TOKEN" \
"https://app.netdata.cloud/api/v3/spaces/$SPACE/rooms/$ROOM/nodes" \
-d '{}'
Per-node response fields:
| Field |
Description |
nd |
Node UUID -- required for any node-targeted call |
mg |
Machine GUID |
nm |
Hostname |
state |
reachable (live) or stale (disconnected) |
v |
Agent version |
labels |
Key-value labels |
hw, os, health, capabilities |
Metadata blocks |
The nd value is what the four domain guides call "node UUID" or
{nodeId} in their endpoint paths.
Common errors
| Symptom |
Likely cause |
| HTTP 401 |
Token missing, malformed, or revoked. Re-create. |
| HTTP 403 |
Token lacks the scope/role for this endpoint or space. |
| HTTP 404 with HTML body |
Wrong path; check method (GET vs POST) and version (/api/v2 vs /api/v3). The API does not enumerate paths via Swagger, so 404 means the path does not exist. |
HTTP 400 with errorCode JSON |
Missing required parameter. The error message names the missing field. |
| Empty/silent response |
Filter excludes everything. Most endpoints return empty data without error. Verify scope/selectors. |
Sensitive data
Cloud responses contain space names, node hostnames, machine GUIDs,
node UUIDs, claim IDs, cloud-provider labels, IP addresses, and other
identifiers. Treat fetched payloads as personal/customer data:
- Do not paste raw response bodies into committed files.
- Do not paste tokens, bearer values, or session ids anywhere.
- For maintainer workflows in this repository, redirect raw output
to
<repo>/.local/audits/... (gitignored) and report only
sanitized summaries upstream.
See <repo>/.agents/sensitive-data-discipline.md for the
full rule and the pre-commit verification grep.
1---
2name: query-netdata-cloud
3description: Query Netdata Cloud via its REST API -- metrics, logs (systemd-journal / windows-events / macos-logs / otel-logs), topology graphs (topology:snmp), network flows (flows:netflow), alerts, dynamic configuration (DynCfg), and generic Functions on a node. Use when the user asks about querying Netdata Cloud, fetching metrics from the cloud, querying logs / topology / netflow / sflow / ipfix through Cloud, listing or modifying configurations via DynCfg, calling agent Functions through Cloud, listing spaces/rooms/nodes, or building a curl command against `app.netdata.cloud`. Pairs with the `query-netdata-agents` skill when direct-agent access is needed.
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/query-netdata-cloud
6---
7
8# Query Netdata Cloud via REST API
9
10This skill teaches end-users (and AI assistants helping them) how to
11construct REST API queries against Netdata Cloud
12(`https://app.netdata.cloud`) using a long-lived API token.
13
14It is split into one shared overview (this file) and four
15domain-specific guides. Each guide is self-contained and includes
16runnable curl commands.
17
18| Domain | Guide |
19|---|---|
20| Time-series metrics | [query-metrics.md](./query-metrics.md) |
21| Logs (`systemd-journal`, `windows-events`, `macos-logs`, `otel-logs`) | [query-logs.md](./query-logs.md) |
22| Topology Functions (`topology:snmp`, ...) | [query-topology.md](./query-topology.md) |
23| Network-flow Functions (`flows:netflow` -- NetFlow / sFlow / IPFIX) | [query-flows.md](./query-flows.md) |
24| Alerts and alert transitions | [query-alerts.md](./query-alerts.md) |
25| Dynamic Configuration (DynCfg) | [query-dyncfg.md](./query-dyncfg.md) |
26| Generic Function invocation (table snapshots + protocol taxonomy) | [query-functions.md](./query-functions.md) |
27| Nodes (per-room enumeration with full metadata) | [query-nodes.md](./query-nodes.md) |
28| Rooms (per-space enumeration) | [query-rooms.md](./query-rooms.md) |
29| Members (per-space user enumeration) | [query-members.md](./query-members.md) |
30| Event feed (audit + activity log) | [query-feed.md](./query-feed.md) |
31| **Operational how-tos (live catalog)** | [how-tos/INDEX.md](./how-tos/INDEX.md) |
32
33### Canonical reference docs (in this repo)
34
35For the query protocol details these guides build on, read the authoritative
36sources directly:
37
38| File | What it covers |
39|---|---|
40| `<repo>/src/plugins.d/FUNCTION_UI_REFERENCE.md` | Functions v3 protocol -- envelope, simple-table vs log-explorer, facets, histograms, charts, field types, pagination, delta mode, PLAY mode, error handling. The single most important reference for any Function work. |
41| `<repo>/src/plugins.d/FUNCTION_UI_SCHEMA.json` | JSON Schema for validating Function responses |
42| `<repo>/src/plugins.d/FUNCTION_TOPOLOGY_SCHEMA.json` | JSON Schema for validating production topology payloads |
43| `<repo>/src/plugins.d/DYNCFG.md` | External-plugin DynCfg protocol (go.d.plugin and other external collectors) |
44| `<repo>/src/daemon/dyncfg/README.md` | Internal DynCfg (high-level and low-level APIs, command enums, lifecycle) |
45
46For querying agents directly (without going through Cloud) -- including
47auto-minting agent bearer tokens from a Cloud token -- see the sibling
48skill [`query-netdata-agents`](../query-netdata-agents/SKILL.md).
49
50---
51
52## Mandatory Requirements (READ FIRST)
53
541. **If you analyze, you author a how-to.** When asked a concrete
55 question about a Netdata environment that isn't already covered
56 by an existing how-to under [`how-tos/`](./how-tos/), you MUST
57 author a new how-to in this directory and add it to
58 [`how-tos/INDEX.md`](./how-tos/INDEX.md) BEFORE completing the
59 task. The catalog is meant to be **live** -- the next assistant
60 should not redo the same analysis from scratch. Keep this
61 catalog operator-facing: recipes here should explain how to fetch
62 or use Cloud data. Developer contract validation for collectors,
63 topology producers, schemas, fixtures, UI adapters, or aggregator
64 handoffs belongs in the relevant project developer skill, not in
65 this public skill.
662. **Use the token-safe wrappers.** Every example in this skill
67 uses `agents_query_cloud` (and friends) from
68 `../query-netdata-agents/scripts/_lib.sh`. Never paste raw
69 `Authorization: Bearer $TOKEN` curl commands -- that exposes
70 the cloud token to the assistant. The wrappers handle auth
71 internally and emit only the response body to stdout.
723. **Provide actionable instructions.** You don't run queries for
73 users. Your role is to teach them. Every response that proposes a
74 query must end in a complete, runnable command (wrapper-based,
75 not raw curl).
76
772. **Never ask for credentials.** Do not request API tokens, Space
78 IDs, or Room IDs. Use placeholders (`YOUR_API_TOKEN`,
79 `YOUR_SPACE_ID`, `YOUR_ROOM_ID`) at the top of your curl examples
80 so the user fills them in locally.
81
823. **Always include a runnable curl command.** A response without a
83 complete `curl -X METHOD ... -H ... -d '...'` block is incomplete.
84 Use a heredoc for the JSON body so the user does not have to
85 escape quotes:
86
87 ```bash
88 read -r -d '' PAYLOAD <<'EOF'
89 { "scope": { "contexts": ["system.cpu"] }, ... }
90 EOF
91 ```
92
934. **Domain-specific gotchas live in the per-domain guide.** For
94 metrics, the most important is `scope.contexts` MUST be set. See
95 the per-domain guide for the rest.
96
97---
98
99## Prerequisites
100
101Three things are needed for any query:
102
103### 1. API Token
104
1051. Login to [app.netdata.cloud](https://app.netdata.cloud)
1062. Click the user icon (lower-left corner -- tooltip shows your name)
1073. Select **User Settings**
1084. Open the **API Tokens** tab
1095. Click the **[+]** button (top-left)
1106. Pick a scope, enter a description, click **Create**
1117. **Copy the token immediately** -- it is shown once.
112
113Recommended scope: `scope:all` (full access) or `scope:grafana-plugin`
114(read-only data endpoints).
115
116### 2. Space ID
117
1181. In the dashboard, click the **gear icon** below the spaces list
119 (tooltip: "Space Settings")
1202. In the **Info** tab, copy the **Space Id**.
121
122### 3. Room ID
123
1241. In Space Settings, open the **Rooms** tab
1252. Click the **>** icon at the right of the row (tooltip: "Room
126 Settings")
1273. In the **Room** tab, copy the **Room Id**.
128
129---
130
131## Authentication
132
133All endpoints accept the cloud token as an HTTP `Authorization`
134header:
135
136```
137Authorization: Bearer YOUR_API_TOKEN
138Content-Type: application/json (for POST endpoints)
139```
140
141GET endpoints do not require the `Content-Type` header but accept it.
142
143---
144
145## Discovery Endpoints (used by every domain)
146
147These endpoints enumerate what the cloud token can see. Use them when
148you don't know the Space ID, Room ID, or node UUID up front.
149
150| Endpoint | Method | Purpose |
151|---|---|---|
152| `/api/v2/accounts/me` | GET | Confirm the token works; returns the user identity. |
153| `/api/v2/spaces` | GET | List spaces visible to this token. |
154| `/api/v2/spaces/{spaceID}/rooms` | GET | List rooms in a space. |
155| `/api/v3/spaces/{spaceID}/rooms/{roomID}/nodes` | POST `{}` | List nodes in a room with full metadata. |
156
157### Example: list spaces
158
159```bash
160TOKEN="YOUR_API_TOKEN"
161
162curl -sS \
163 -H "Authorization: Bearer $TOKEN" \
164 "https://app.netdata.cloud/api/v2/spaces"
165```
166
167Each space record contains `id`, `slug`, `name`, `permissions[]`, and
168metadata. Match by `name` or `slug` to find the space you want.
169
170### Example: list rooms in a space
171
172```bash
173TOKEN="YOUR_API_TOKEN"
174SPACE="YOUR_SPACE_ID"
175
176curl -sS \
177 -H "Authorization: Bearer $TOKEN" \
178 "https://app.netdata.cloud/api/v2/spaces/$SPACE/rooms"
179```
180
181### Example: list nodes in a room
182
183```bash
184TOKEN="YOUR_API_TOKEN"
185SPACE="YOUR_SPACE_ID"
186ROOM="YOUR_ROOM_ID"
187
188curl -sS -X POST \
189 -H 'Content-Type: application/json' \
190 -H "Authorization: Bearer $TOKEN" \
191 "https://app.netdata.cloud/api/v3/spaces/$SPACE/rooms/$ROOM/nodes" \
192 -d '{}'
193```
194
195Per-node response fields:
196
197| Field | Description |
198|---|---|
199| `nd` | Node UUID -- required for any node-targeted call |
200| `mg` | Machine GUID |
201| `nm` | Hostname |
202| `state` | `reachable` (live) or `stale` (disconnected) |
203| `v` | Agent version |
204| `labels` | Key-value labels |
205| `hw`, `os`, `health`, `capabilities` | Metadata blocks |
206
207The `nd` value is what the four domain guides call "node UUID" or
208`{nodeId}` in their endpoint paths.
209
210---
211
212## Common errors
213
214| Symptom | Likely cause |
215|---|---|
216| HTTP 401 | Token missing, malformed, or revoked. Re-create. |
217| HTTP 403 | Token lacks the scope/role for this endpoint or space. |
218| HTTP 404 with HTML body | Wrong path; check method (GET vs POST) and version (`/api/v2` vs `/api/v3`). The API does not enumerate paths via Swagger, so 404 means the path does not exist. |
219| HTTP 400 with `errorCode` JSON | Missing required parameter. The error message names the missing field. |
220| Empty/silent response | Filter excludes everything. Most endpoints return empty data without error. Verify scope/selectors. |
221
222---
223
224## Sensitive data
225
226Cloud responses contain space names, node hostnames, machine GUIDs,
227node UUIDs, claim IDs, cloud-provider labels, IP addresses, and other
228identifiers. Treat fetched payloads as personal/customer data:
229
230- Do not paste raw response bodies into committed files.
231- Do not paste tokens, bearer values, or session ids anywhere.
232- For maintainer workflows in this repository, redirect raw output
233 to `<repo>/.local/audits/...` (gitignored) and report only
234 sanitized summaries upstream.
235
236See `<repo>/.agents/sensitive-data-discipline.md` for the
237full rule and the pre-commit verification grep.