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