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