Traffic (Read)

Get Bulk Link Utilization

GET /api/v1/traffic/links?area_id={areaID}
GET /api/v1/traffic/links?pi_id={piID}
GET /api/v1/traffic/links?rd_id={rdID}
GET /api/v1/traffic/links?network_id={networkID}

Get the max utilization percentage for every link in the given scope that has SNMP traffic data. Used by the "By Utilization" color mode.

Query parameters (exactly one required):

area_id — UUID of a single area
pi_id — UUID of a protocol instance (resolves all child areas)
rd_id — UUID of a routing domain (resolves all child areas)
network_id — UUID of a network (resolves all child areas)

Response: 200 OK

[
  {
    "link_id": "uuid",
    "utilization_pct": 42.7,
    "source_name": "core-1",
    "source_router_id": "198.51.100.150",
    "target_name": "dist-3",
    "target_router_id": "203.0.113.10"
  }
]

Notes:

utilization_pct is GREATEST(source, target) — the higher of the two link endpoints.
source_name / target_name are the device hostnames (SNMP sysName). source_router_id / target_router_id are OSPF router IDs. These are included so the response is self-contained (no cross-reference with topology graph needed).
Links with state = 'down' are excluded.
Links with no SNMP stats on either endpoint are excluded (returned as empty array entry).
Returns [] when no links have traffic data.

Error responses:

400 Bad Request — No scope parameter provided

Get Interface Traffic History

GET /api/v1/traffic/interface/{interfaceID}?from={from}&to={to}&limit={limit}

Get historical traffic statistics for a specific interface.

Path parameters:

interfaceID (required) — UUID of the interface

Query parameters:

from (optional) — Start time filter, ISO 8601 timestamp (e.g., "2026-02-17T00:00:00Z")
to (optional) — End time filter, ISO 8601 timestamp (e.g., "2026-02-18T00:00:00Z")
limit (optional) — Maximum number of records to return (default: 100)

Response: 200 OK

[
  {
    "id": "uuid",
    "interface_id": "uuid",
    "timestamp": "2026-02-18T14:30:00Z",
    "in_octets": 1234567890,
    "out_octets": 987654321,
    "in_rate_bps": 8500000,
    "out_rate_bps": 6200000,
    "in_pps": 12000,
    "out_pps": 9500,
    "utilization_in": 0.085,
    "utilization_out": 0.062,
    "if_speed": 1000000000,
    "if_oper_status": "up",
    "in_errors": 0,
    "out_errors": 0,
    "in_discards": 0,
    "out_discards": 0
  }
]

Notes:

in_rate_bps and out_rate_bps are calculated rates in bits per second derived from counter deltas.
utilization_in and utilization_out are decimal fractions (0.0 to 1.0) representing the percentage of if_speed consumed.
if_speed is in bits per second (e.g., 1000000000 for 1 Gbps).
Returns [] when no traffic data is available for the specified interface or time range.

Error responses:

400 Bad Request — Invalid interface ID, invalid timestamp format, or invalid limit
404 Not Found — Interface does not exist

Get Interface Utilization History

GET /api/v1/traffic/interface/{interfaceID}/history?from={from}&to={to}

Get hourly-bucketed utilization history for a specific interface. Data comes from the utilization_history table (populated by the SNMP poller). Used by the UtilizationChart component in LinkDetailDrawer and NodeDetailDrawer.

Path parameters:

interfaceID (required) — UUID of the interface

Query parameters:

from (optional) — Start time filter, RFC 3339 timestamp. Default: 24 hours ago.
to (optional) — End time filter, RFC 3339 timestamp. Default: now.

Response: 200 OK

[
  {
    "bucket_time": "2026-03-04T14:00:00Z",
    "max_util": 67.3,
    "avg_util": 42.1,
    "samples": 12
  }
]

Notes:

max_util and avg_util are percentages (0-100).
samples is the number of raw polls aggregated into the hourly bucket.
One row per hour in the requested range.
Returns [] when no utilization data is available.

Error responses:

400 Bad Request — Invalid interface ID or timestamp format

Get Link Traffic

GET /api/v1/traffic/link/{linkID}

Get the latest traffic statistics for both endpoints of a link.

Path parameters:

linkID (required) — UUID of the link

Response: 200 OK

{
  "source_stats": {
    "id": "uuid",
    "interface_id": "uuid",
    "timestamp": "2026-02-18T14:30:00Z",
    "in_octets": 1234567890,
    "out_octets": 987654321,
    "in_rate_bps": 8500000,
    "out_rate_bps": 6200000,
    "in_pps": 12000,
    "out_pps": 9500,
    "utilization_in": 0.085,
    "utilization_out": 0.062,
    "if_speed": 1000000000,
    "if_oper_status": "up",
    "in_errors": 0,
    "out_errors": 0,
    "in_discards": 0,
    "out_discards": 0
  },
  "target_stats": null
}

Notes:

source_stats corresponds to the link's source device interface.
target_stats corresponds to the link's target device interface.
Either field may be null if the SNMP poller has not yet collected data for that endpoint, or if the endpoint device has no SNMP target configured.

Error responses:

400 Bad Request — Invalid link ID
404 Not Found — Link does not exist

Get Device Traffic

GET /api/v1/traffic/device/{deviceID}

Get the latest traffic statistics for all interfaces on a device.

Path parameters:

deviceID (required) — UUID of the device

Response: 200 OK

[
  {
    "id": "uuid",
    "interface_id": "uuid",
    "timestamp": "2026-02-18T14:30:00Z",
    "in_octets": 1234567890,
    "out_octets": 987654321,
    "in_rate_bps": 8500000,
    "out_rate_bps": 6200000,
    "in_pps": 12000,
    "out_pps": 9500,
    "utilization_in": 0.085,
    "utilization_out": 0.062,
    "if_speed": 1000000000,
    "if_oper_status": "up",
    "in_errors": 0,
    "out_errors": 0,
    "in_discards": 0,
    "out_discards": 0
  }
]

Notes:

Returns one entry per interface that has SNMP traffic data.
Returns [] if the device has no SNMP target or no traffic data has been collected yet.

Error responses:

400 Bad Request — Invalid device ID
404 Not Found — Device does not exist

Boost Traffic Polling

POST /api/v1/traffic/boost

Request the SNMP poller to temporarily accelerate polling for the specified devices. Used by the Link Detail Drawer to get near-real-time traffic stats while the user is viewing them.

Auth: Any authenticated user.

Request body:

{
  "device_ids": ["uuid1", "uuid2"],
  "action": "boost"
}

Field	Type	Required	Description
`device_ids`	`string[]`	Yes	Device UUIDs to boost (max 10)
`action`	`string`	Yes	`"boost"` to start fast polling, `"unboost"` to cancel

Response: 204 No Content

Notes:

Publishes a TrafficBoostEvent to NATS osprey.traffic.boost
SNMP poller accelerates to 5s intervals for matched targets
Boost auto-expires after 60s TTL; frontend sends heartbeat every 30s
Best-effort: returns 204 even if NATS publish fails