Query agent Functions via Netdata Cloud

This guide is part of the query-netdata-cloud skill. Read the SKILL.md prerequisites first.

This file documents the generic Function transport: the URL, the standard response envelope, the info discovery query, the four Function families and where each family's data lives in the response.

For three of the four families there is a dedicated guide:

• Logs family (table-history with facets+histogram): query-logs.md
• Topology family (graph: actors+links): query-topology.md
• Flows family (network-flow records): query-flows.md

The table-snapshot family (full dataset in each response) is covered here.

For querying agents directly (without going through Cloud) -- which includes the transparent Cloud-token to agent-bearer mint flow -- see the sibling skill query-netdata-agents.

Mandatory Requirements (READ FIRST)

1. Provide actionable instructions. Every recommendation ends in a runnable curl command.
2. Never request credentials. Use YOUR_API_TOKEN and YOUR_NODE_UUID placeholders.
3. Always start with {"info":true} when you don't already know the parameter set of the target Function. The info response is authoritative -- this skill's tables can be stale relative to the running agent.
4. Function names are case-sensitive (e.g. systemd-journal, topology:snmp, flows:netflow).

Function classes

The canonical Functions v3 protocol (<repo>/src/plugins.d/FUNCTION_UI_REFERENCE.md) formally defines two Function classes, distinguished by the has_history flag in the info response:

Two additional type values are used by purpose-built Functions that build on the same envelope but emit non-tabular data:

For full protocol semantics (facet pills, histograms, charts configuration, anchor/delta/PLAY modes, error handling, edge cases), the authoritative source is <repo>/src/plugins.d/FUNCTION_UI_REFERENCE.md. This skill summarizes the surface that matters for a Cloud-side curl client; the reference covers everything else.

Standard response envelope

Every Function -- regardless of family -- wraps its output in this envelope. Verified live against the agent's systemd-journal, topology:snmp, and flows:netflow Functions, and against the agent emit code at src/web/api/functions/function-metrics-cardinality.c:26-39,92 plus per-collector wrappers.

status >= 400 responses follow the same envelope but include an errorMessage / errorMsgKey instead of data.

info=true discovery

The single most important call to make before constructing a real query: pass {"info": true} and read accepted_params plus required_params. The agent itself is the authoritative source -- if a parameter exists there, the Function accepts it; if it doesn't, no other doc matters.

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
FN="systemd-journal"

read -r -d '' PAYLOAD <<'EOF'
{ "info": true }
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=$FN" \
  -d "$PAYLOAD"

required_params widget schema

Each entry of required_params is a UI-widget descriptor that tells a client what to render and what values are valid. Verified against the emit code in src/collectors/network-viewer.plugin/network-viewer.c:1601-1731 and across the topology / logs / flows Functions.

Widget type values seen in source:

The widget array is the contract between the agent and any UI or script. To programmatically construct a valid body for a Function, walk required_params and emit the body shape it implies. There is no central widget builder API in source -- each collector emits the array directly via buffer_json_* calls -- so the agent's own info=true response is the only authoritative place to read the schema for a specific node version.

Endpoints

List Functions on the nodes in a room

POST /api/v3/spaces/{spaceID}/rooms/{roomID}/functions

TOKEN="YOUR_API_TOKEN"
SPACE="YOUR_SPACE_ID"
ROOM="YOUR_ROOM_ID"

read -r -d '' PAYLOAD <<'EOF'
{
  "scope":     { "nodes": [] },
  "selectors": { "nodes": ["*"] }
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v3/spaces/$SPACE/rooms/$ROOM/functions" \
  -d "$PAYLOAD"

Response top-level: functions[] (each entry: name, version, help, ni[], tags, access[], priority), nodes[] (each { ni, mg, nd, nm, st }), agents[], versions. Match functions[].ni to nodes[].ni to find which nodes expose a given Function.

Invoke a Function on a node

POST /api/v2/nodes/{nodeId}/function?function={functionName}

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"
FN="processes"

read -r -d '' PAYLOAD <<'EOF'
{
  "last":    50,
  "timeout": 30000
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=$FN" \
  -d "$PAYLOAD"

Optional headers:

Frequently registered Functions

Function availability is per-node. The listing endpoint above is the only authoritative source. Below are common Functions on a stock Linux Netdata install (verified live):

Database collectors register a per-collector family of Functions when active: <collector>:top-queries, <collector>:running-queries, <collector>:deadlock-info, <collector>:error-info -- e.g. postgres:top-queries, mysql:top-queries, mssql:deadlock-info. The listing endpoint reports them when the collector is enabled.

Examples (table-snapshot Functions)

For logs / topology / flows examples, see the per-family guides linked at the top.

Example 1: top processes by CPU

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"

read -r -d '' PAYLOAD <<'EOF'
{
  "last":    50,
  "timeout": 30000
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=processes" \
  -d "$PAYLOAD" \
  | jq '.data | length, (.[0:3])'

Example 2: discover a Function's parameter widget set

read -r -d '' PAYLOAD <<'EOF'
{ "info": true }
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=network-connections" \
  -d "$PAYLOAD" \
  | jq '.required_params | map({id, type, name, options: (.options | length // 0)})'

Example 3: list the Functions on a single node

read -r -d '' PAYLOAD <<'EOF'
{
  "scope":     { "nodes": ["YOUR_NODE_UUID"] },
  "selectors": { "nodes": ["*"] }
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v3/spaces/$SPACE/rooms/$ROOM/functions" \
  -d "$PAYLOAD" \
  | jq -r '.functions[] | "\(.name)\t\(.tags // "")\t\(.help)"'

Limits and gotchas

• Cloud default timeout is 120 s for Function calls; pass "timeout": <ms> in the body for slower Functions but Cloud may impose its own ceiling.
• Response is NOT streamed. The Cloud proxy collects the full agent response and returns it in one body. For potentially huge results (logs, flows), narrow the time window or use the Function's pagination (last, anchor) rather than relying on streaming.
• Node must be reachable. A stale node returns HTTP 400 with errorMsgKey: "ErrInstanceNotReachable". Verify with the discovery endpoints in SKILL.md.
• Permission: the cloud token must include PermissionFunctionExec on the target space. scope:all works; scope:grafana-plugin does NOT.
• Function name is case-sensitive -- wrong casing returns 400.
• info=true does NOT bypass auth. ACL is enforced on every call regardless of body.
• The agent's own info=true response is authoritative for parameters. Tables in this skill can drift relative to the running version. When in doubt, ask the agent.