Fleet-wide busiest/erroring interfaces. Ranks `(node,ifindex)` by a query-time rate, then joins node + interface names (and speed) from PostgreSQL.

GET

/api/v1/metrics/interface-top

curl --request GET \
  --url 'https://example.com/api/v1/metrics/interface-top?metric=example' \
  --header 'Authorization: Bearer <token>'

Authorizations

• bearer

Parameters

Query Parameters

metric

required

string

throughput | in_bps | out_bps | errors | discards.

agg

string

limit

integer

Responses

200

The busiest or most-erroring interfaces, ranked; partial says the scope filter may have shortened the list

Media typeapplication/json

A ranked Top-N result.

object

entries

required

The ranked rows, highest first, at most the requested limit.

Array<object>

One ranked interface in a fleet interface Top-N.

object

if_alias

string | null

if_name

string | null

if_speed_bps

Configured speed (bits/sec) for util%; null if unknown.

integer | null format: int64

ifindex

required

integer format: int32

node_id

required

string format: uuid

node_name

required

string

value

required

Bits/sec for throughput metrics, errors|discards per second otherwise.

number format: double

partial

required

true when this ranking covers only the groups the calling account may see and entries it is entitled to may be missing. Always false for an account with unrestricted visibility.

boolean

Example^generated

{
  "entries": [
    {
      "if_alias": "example",
      "if_name": "example",
      "if_speed_bps": 1,
      "ifindex": 1,
      "node_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "node_name": "example",
      "value": 1
    }
  ],
  "partial": true
}

400

metric is not one of throughput|in_bps|out_bps|errors|discards, or agg is unsupported

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

401

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Role lacks the read permission

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object

error

required

object

code

required

Stable machine-readable code. Clients branch on this, never on the message.

string

message

required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}