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:

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)

1. 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.

2. 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.

3. 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).

4. 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.

5. 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:

   bashCopy

   read -r -d '' PAYLOAD <<'EOF'
   { "scope": { "contexts": ["system.cpu"] }, ... }
   EOF
   

6. 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

1. Login to app.netdata.cloud
2. Click the user icon (lower-left corner -- tooltip shows your name)
3. Select User Settings
4. Open the API Tokens tab
5. Click the [+] button (top-left)
6. Pick a scope, enter a description, click Create
7. 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

1. In the dashboard, click the gear icon below the spaces list (tooltip: "Space Settings")
2. In the Info tab, copy the Space Id.

3. Room ID

1. In Space Settings, open the Rooms tab
2. Click the > icon at the right of the row (tooltip: "Room Settings")
3. 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.

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:

The nd value is what the four domain guides call "node UUID" or {nodeId} in their endpoint paths.

Common errors

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.