cdnca

API reference

/v1/node-traffic

1 operations

← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures

MethodPathSummaryAuth
GET/v1/node-trafficRead interval node traffic, not cumulative lifetime countersSession

Contract file：api/control-node-realtime.openapi.yaml

Operation details

GET /v1/node-traffic

Read interval node traffic, not cumulative lifetime counters

operationId
getNodeTraffic
Auth
  • Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
Required permissions

The contract has no separate permission annotation; see the description below and the 403 response.

Description (from the contract)

Requires nodes.read or platform.admin in a platform scope. external_only differences each NIC before selecting the current sample's default-route devices. A route change therefore cannot create a lifetime-counter spike. At least two known snapshots with a baseline for each selected NIC are required. Missing evidence is not a zero. Explicitly excluded NICs are omitted after automatic selection. This is monitoring, not billable usage.

Parameters

getNodeTraffic Parameters
NameInTypeRequiredDescription
nodequerystring(uuid)Yes—
external_onlyquerybooleanNoLiteral true or false, at most once. Default false preserves old API callers. The management UI explicitly sends true by default. Filters bandwidth/traffic by each sample's reported network_selection; missing or unavailable selection never means all interfaces. Other metric types are unchanged. False exposes all original NIC facts for manual diagnostics.
startquerystring(date-time)NoStart of a window no longer than 31 days; defaults to one hour ago for realtime and one day ago for traffic.
endquerystring(date-time)NoDefaults to now; must not precede start.
limitqueryintegerNo—
excl_nicquerystringNoSpace-separated interface names to exclude. excluded_nic is a compatible alias; both sets are combined.

Responses

getNodeTraffic Responses
StatusDescription
200Interval bytes at each sample time, without billing settlement claims.

Fields：msg: string code: integer count: integer data: array<object>

400Invalid parameters; validation_error.
401Authentication required.
403Platform scope and nodes.read or platform.admin required.
404Node absent from the caller scope; node_metrics_not_found.
503Metrics runtime unavailable; node_metrics_unavailable.

What to do on failure

  • 400 Fix the parameters or body per the field list; do not retry unchanged.
  • 401 Check the credential format and whether it expired or was rotated.
  • 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
  • 404 The resource does not exist or belongs to another tenant.
  • 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list