Query Netdata Cloud

Query Netdata Cloud

Use this skill for Cloud REST queries and for reviewing or explaining those queries. Load the guide for the requested domain; the sibling Agent skill owns direct access and the shared query helpers.

Choose The Task

• Explain or review: inspect the relevant guide and helper as reference material. Loading this skill does not authorize live requests, credential loading or configuration changes. An explanation need not end in a command.
• Run a requested query: follow Prerequisites and Safe Execution, then the selected guide. Preserve authorization already given for the task; do not ask again for ordinary query steps.
• Change configuration or invoke a state-changing Function: establish that the user requested that operation. A request to inspect data does not authorize DynCfg updates or arbitrary Function execution. HTTP method alone does not establish whether a request changes state; consult the Function or action contract.

For an execution recipe, provide a complete runnable wrapper invocation with locally supplied inputs and the response fields needed for the question. For discovery, use the endpoint appropriate to the missing identifier. Domain requirements remain in their guides; metric queries MUST set scope.contexts as explained in the metrics guide.

Domain Guides

Prerequisites

Explanation and saved-data review need no credentials. Executable recipes require Bash, Git, curl, jq and a checkout containing the shared helper, plus access to the chosen Cloud host. Configure NETDATA_CLOUD_TOKEN and NETDATA_CLOUD_HOSTNAME locally; never request credential values in conversation. Use identifier placeholders or local discovery for space, room and node IDs. Only endpoints that include those IDs require them.

Access And Discovery covers token setup, identifier lookup and error diagnosis. Helper configuration owns the environment keys and trusted .env loading. Source the helper and load configuration only for authorized execution:

source "$(git rev-parse --show-toplevel)/docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh"
agents_load_env

Safe Execution

Credential-bearing requests MUST use agents_query_cloud, agents_query_agent or agents_call_function from the shared helper. Do not construct raw bearer-auth curl examples or print credentials. Ordinary local processing and unauthenticated probes MAY use ordinary commands when they capture or suppress sensitive responses.

Shared Safe Execution owns credential and response handling. The wrappers mask known request-auth values in their command log; they forward responses unchanged and do not scrub arbitrary request-body fields. Keep sensitive bodies in private local files (the body argument accepts @file) and capture or project sensitive responses before display. Do not display credential-issuing endpoint output through these wrappers. Avoid shell tracing around credentials. Use the minimum response fields needed for the task.

For JSON bodies, use a quoted heredoc in command substitution, or a private payload file. The helper enables set -e; an empty-delimiter read returns failure at EOF and stops the recipe. For example, after setup:

SPACE="YOUR_SPACE_ID"
ROOM="YOUR_ROOM_ID"
PAYLOAD="$(cat <<'JSON'
{}
JSON
)"
agents_query_cloud POST \
  "/api/v3/spaces/$SPACE/rooms/$ROOM/nodes" "$PAYLOAD" \
  | jq '{node_count: (.nodes | length)}'

Cloud payloads can contain customer identifiers, hostnames, labels, addresses and secrets. Raw responses MUST NOT go into committed files; token, bearer and session values MUST NOT be pasted into conversation or shared artifacts. Repository workflows capture raw output privately under <repo>/.local/audits/ and report sanitized summaries. Repository contributors follow .agents/sensitive-data-discipline.md; outside a checkout apply the same redaction to shared artifacts. The public helpers' exact interfaces live in Helper Interfaces.