get_interface_series
const url = 'https://example.com/api/v1/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/interfaces/1/series';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/v1/nodes/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/interfaces/1/series \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Node id
The interface’s row key: its SNMP ifIndex, or for a Cisco Meraki switch port the number Yagra gives it (get_node_status lists both)
Query Parameters
Section titled “Query Parameters”Responses
Section titled “Responses”In/out throughput in bits/sec and in unicast packets/sec, plus error and discard rates, all on one shared timestamp axis
Per-interface time-series for the node-detail Interfaces pane: In/Out throughput in bits per second and in packets per second, In/Out errors, and In/Out discards.
Only the throughput pair has two units, and that is a property of the MIB rather than a
shortcut: IF-MIB counts errored and discarded frames but never their octets, so
in_errors/out_errors/in_discards/out_discards are packets per second and there is no
bits-per-second form of them to ask for.
in_ucast_pps/out_ucast_pps are unicast only (ifHCInUcastPkts/ifHCOutUcastPkts);
multicast and broadcast frames are not counted. The name says so rather than the documentation
alone, so that a future total can be added as a new field instead of silently changing what an
existing number means. Two consequences for a client: on a link carrying heavy broadcast the
packet rate reads low, and dividing bits by packets overstates the average frame size.
Errors and discards are separate because their causes are: an error is a frame that arrived damaged (cabling, optics, NIC), a discard is a frame the device chose to drop with nothing wrong with it (congestion, queue overflow, ACL). Reading one for the other sends an operator to the wrong place, so the UI draws them as two charts rather than one — ADR-046 Inc.4.
rx_power_dbm/tx_power_dbm are the transceiver’s received and transmitted optical power in
dBm, and differ from the six above in three ways worth knowing (ADR-062). They are gauges,
not counter rates — the value is read as reported, not differentiated. They are normally
negative: a healthy receive level is roughly −3 to −20 dBm, and 0 dBm means one milliwatt, not
“nothing”. And they are populated only for optical ports — a copper port, a virtual
interface, or a device whose transceiver MIB Yagra does not speak leaves both arrays entirely
null, which is the intended way for a client to tell an optical interface from any other.
The figure is the module’s reading; a multi-lane transceiver (QSFP) reports its first lane
rather than an aggregate, and per-lane series are deliberately not offered.
All ten share one timestamps axis — the union of returned points, with null in the gaps —
so the chart gets aligned series rather than ten independently-indexed ones. Derived at query
time (ADR-012); empty when there is no history. The packet counters entered the default
collection set in ADR-060 and the optical readings in ADR-062, so on a deployment upgraded from
an earlier version those arrays are empty for every window predating that upgrade while the bps
arrays are populated.
A Cisco Meraki switch port (ADR-167) is read differently. Its in_bps/out_bps are the
five-minute averages the Dashboard reports, stored as they came — Meraki gives no counter, so
these two are the exception to “derived at query time” — and they arrive 12 to 17 minutes late.
The Dashboard gives no packet, error or discard counts either, so for such a port those six
arrays are always empty: that is “not collected”, never “no errors”. Its ifindex is the
number Yagra gives the port (the port number, or a hash of a module port’s id), not an SNMP
ifIndex.
object
Examplegenerated
{ "in_bps": [ 1 ], "in_discards": [ 1 ], "in_errors": [ 1 ], "in_ucast_pps": [ 1 ], "out_bps": [ 1 ], "out_discards": [ 1 ], "out_errors": [ 1 ], "out_ucast_pps": [ 1 ], "rx_power_dbm": [ 1 ], "timestamps": [ 1 ], "tx_power_dbm": [ 1 ]}No valid bearer token
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}Role lacks the read permission
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
object
Stable machine-readable code. Clients branch on this, never on the message.
Operator-facing sentence. Safe to display; never carries an internal error’s own text.
Examplegenerated
{ "error": { "code": "example", "message": "example" }}