Query network-flow Functions via Netdata Cloud

This guide is part of the query-netdata-cloud skill. Read the SKILL.md prerequisites first. For the generic Function transport, see query-functions.md.

Flow Functions return network-flow records (NetFlow / sFlow / IPFIX) ingested by the agent's flow collector. Their dataset is table-shaped (one row per flow tuple) AND time-windowed AND faceted, sitting between table snapshots (processes) and log queries (systemd-journal).

Function names registered today

Verified live and in source:

The flows: prefix is the canonical namespace; only netflow is registered today. The Function name covers all three protocols (the collector parses NetFlow, IPFIX, and sFlow into a single record schema).

Endpoint and request

Standard Cloud Function-call endpoint:

POST /api/v2/nodes/{nodeId}/function?function=flows:netflow

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"

read -r -d '' PAYLOAD <<'EOF'
{
  "mode":     "flows",
  "view":     "table-sankey",
  "after":    -3600,
  "before":   0,
  "group_by": ["SRC_AS_NAME", "PROTOCOL", "DST_AS_NAME"],
  "sort_by":  "bytes",
  "top_n":    100
}
EOF

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

Modes

The Function has three modes selected by the mode body field:

Body parameters

Verified against src/crates/netflow-plugin/src/api/flows/handler.rs:

Response envelope

Flow Functions wrap their content in the standard Function envelope (same shape as topology and logs):

data object -- mode flows, view table-sankey

data object -- mode flows, view timeseries

Replaces flows[] with metric (string) and chart (object); used for line/area charts of bytes-per-second / packets-per-second broken down by the group-by tuple.

data object -- mode flows, geo views (country-map, state-map, city-map)

Returns geo-keyed aggregations (per-country / per-state / per-city totals) suitable for map rendering.

data object -- mode autocomplete

Examples

Example 1: top-100 talker pairs by bytes, last hour

TOKEN="YOUR_API_TOKEN"
NODE="YOUR_NODE_UUID"

read -r -d '' PAYLOAD <<'EOF'
{
  "mode":     "flows",
  "view":     "table-sankey",
  "after":    -3600,
  "before":   0,
  "group_by": ["SRC_ADDR", "DST_ADDR"],
  "sort_by":  "bytes",
  "top_n":    100
}
EOF

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://app.netdata.cloud/api/v2/nodes/$NODE/function?function=flows:netflow" \
  -d "$PAYLOAD" \
  | jq '.data.flows[:5]'

Example 2: breakdown of TCP traffic by AS name, with histogram

read -r -d '' PAYLOAD <<'EOF'
{
  "mode":       "flows",
  "view":       "timeseries",
  "after":      -86400,
  "before":     0,
  "selections": { "PROTOCOL": ["TCP"] },
  "group_by":   ["DST_AS_NAME"],
  "sort_by":    "bytes",
  "top_n":      25
}
EOF

Example 3: country-map of egress bytes

read -r -d '' PAYLOAD <<'EOF'
{
  "mode":     "flows",
  "view":     "country-map",
  "after":    -3600,
  "before":   0,
  "group_by": ["DST_COUNTRY"],
  "sort_by":  "bytes",
  "top_n":    500
}
EOF

Example 4: autocomplete for a destination IP filter

read -r -d '' PAYLOAD <<'EOF'
{
  "mode":  "autocomplete",
  "field": "DST_ADDR",
  "term":  "10.0.0."
}
EOF

For CIDR autocomplete, loose address and prefix-length fragments are accepted. Digits after / are an autocomplete fragment, not a completed selection: /1 considers /1 and /10 through /19. One trailing dot before / is also tolerated after one through three complete IPv4 octets, so 10.1./1 is equivalent to 10.1/1:

{
  "mode":  "autocomplete",
  "field": "DST_ADDR",
  "term":  "10.1/1"
}

The two complete address octets naturally imply 10.1.0.0/16, so that candidate is ranked first when the retained DST_ADDR vocabulary contains an address in it. Candidates containing no retained destination address are omitted, so another canonical network may be first. Use one of the returned canonical values in selections:

{
  "mode":       "flows",
  "view":       "timeseries",
  "after":      -86400,
  "before":     0,
  "selections": {"DST_ADDR": ["10.1.0.0/16", "2001:db8::7"]},
  "group_by":   ["SRC_ADDR"],
  "sort_by":    "bytes",
  "top_n":      25
}

Example 5: discover the live parameter set first

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=flows:netflow" \
  -d "$PAYLOAD" \
  | jq '{accepted_params, required_params}'

Limits and gotchas

• Cloud timeout default 120 s. Wide-window queries (after: -86400) over high-volume agents can hit it. Narrow the time window or filter via selections.
• top_n is enumerated, not free. Allowed values are 25, 50, 100, 200, 500. Other integers are rejected.
• group_by accepts up to 10 fields. The order matters -- it's the tuple ordering for the aggregation key.
• CIDR shorthand is autocomplete-only. Direct selections must contain a complete IPv4/IPv6 address and prefix such as 10.0.0.0/8, not 10/8. Valid non-network addresses are normalized before matching. Address-field CIDRs use the same raw-tier availability as exact address filters.
• CIDR suggestions are retention-wide. They prove that the selected field contains a matching address somewhere in retained data. The current time window and other selections can still make the selected CIDR return no rows.
• Negative selections are not supported. The current contract is OR between values of one field and AND between fields.
• AS names depend on the configured GeoIP/AS database. If the collector has no AS database, SRC_AS_NAME / DST_AS_NAME will be empty strings. Same for country/city fields.
• Privacy: flow records reveal who-talks-to-whom and how much. Treat raw output as production-sensitive; never paste into committed files. Direct working output to <repo>/.local/audits/... (gitignored).
• Sampled vs full flows: NetFlow v5/v9 and sFlow are sampled by source devices; reported byte/packet counts are scaled by the sample rate. The collector reports raw counts -- consult source-device sampling configuration when interpreting absolute volumes.
• Function is L3-only. No L2 visibility (use topology Functions for L2). No application-layer dissection (use logs).