Metrics#
The Prometheus scrape endpoint, and the time-series history behind the dashboard charts.
2 operations. Roles, error format and pagination are common to the whole API — see the REST API overview.
Authentication
Use a named bearer token. Every endpoint except POST /api/v1/auth/login,
POST /api/v1/auth/enrol and GET /api/v1/system/health requires one. A super-user creates a
token with POST /api/v1/auth/tokens; the plaintext (bngtok_…) is returned exactly once at
creation and only a SHA-256 hash is stored on the appliance, so a lost token is replaced rather
than recovered. Send it on every request:
Each token carries a fixed role (read-only, operator or super-user) and is exempt from CSRF
checks. This is the single credential you need for scripts, integrations and monitoring.
Accounts and tokens share one identity model with the appliance CLI (login.users). Repeated
authentication failures lock the account/source-IP pair out temporarily (HTTP 423 on login).
Session cookies (bundled web UI only)
The appliance also accepts an interactive session cookie, which is how the bundled web UI authenticates. It is documented for completeness — API clients should not use it. It is bound to a login session and obliges the caller to manage a CSRF token, neither of which suits automation.
POST /api/v1/auth/login with username + password (and a TOTP code when enrolled) sets the
bng_session cookie and returns a csrfToken (also available from GET /api/v1/auth/whoami).
Cookie-authenticated mutating requests (anything other than GET/HEAD/OPTIONS) must also send
that value in the X-CSRF-Token header or they are rejected with 403.
One endpoint refuses the cookie outright: GET /api/v1/metrics, the Prometheus scrape, accepts a
bearer token only, so that a scraper can never keep a login session alive.
NetavoBNG Management API v1#
Metrics#
GET /api/v1/metrics#
Prometheus scrape: every appliance metric, in text exposition format.
Description
Returns the Prometheus text exposition format (version 0.0.4): everything the
SNMP MIB serves — sessions, data-plane health, per-worker and per-port counters, drops by
reason and by pipeline phase, punts by class, CGN, FIB, IPsec and address pools — plus the
active-alarm table. Metric names begin netavo_bng_.
Authenticate with a named API token (`Authorization: Bearer bngtok_…`); the read-only role
is enough. A browser session cookie is **not** accepted here, so a scraper can never hold a
login session open. Point Prometheus at it with `metrics_path: /api/v1/metrics`,
`scheme: https` and `authorization.credentials_file`.
The response is cached for one stats-sample interval (`snmp.sampleIntervalSeconds`, 5 s by
default), so scraping more often than that returns the same numbers. There are no
per-subscriber series; the one family per circuit is the layer-2 hand-off's
(`netavo_bng_l2xc_*`, docs/design/55 §55.9), at most one series per handed-off circuit.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/metrics/history#
Dashboard time series: session counts and per-port throughput.
Description
Returns parallel arrays keyed by the shared times axis: total sessions,
sessions per access encapsulation, session up/down rates, and per-port RX/TX bit rates.
Samples are kept in memory only (up to 24 h, 10 s resolution; longer ranges are
downsampled), so history restarts with the control plane. Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
range |
query | string | 1h | No | Window to return: "1h", "6h" or "24h" (default "1h"; anything else falls back to 1h). |
Responses
{
"intervalSeconds": 10,
"times": [
"2026-08-03T10:23:40Z",
"2026-08-03T10:23:50Z",
"2026-08-03T10:24:00Z"
],
"totalSessions": [
1840,
1841,
1842
],
"byEncap": {
"ipoe": [
210,
210,
211
],
"pppoeLocal": [
1418,
1419,
1419
],
"pppoeLac": [
96,
96,
96
],
"l2tp": [
116,
116,
116
]
},
"sessionsUp": [
3,
2,
4
],
"sessionsDown": [
1,
1,
3
],
"ports": [
{
"portId": 0,
"label": "MS3 NNI 2",
"rxBps": [
4182946816.0,
4190338048.0,
4176510976.0
],
"txBps": [
812304384.0,
818941952.0,
809467904.0
]
}
]
}
Schema of the response body
{
"required": [
"intervalSeconds",
"times",
"totalSessions",
"byEncap",
"sessionsUp",
"sessionsDown",
"ports"
],
"type": "object",
"properties": {
"intervalSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Native sampling interval (seconds); longer ranges are downsampled.",
"format": "int32"
},
"times": {
"type": "array",
"items": {
"type": "string",
"format": "date-time"
},
"description": "UTC sample timestamps; every other array aligns to this axis."
},
"totalSessions": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"description": "Active session count per sample."
},
"byEncap": {
"$ref": "#/components/schemas/MetricsByEncap"
},
"sessionsUp": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"description": "Sessions established during each interval."
},
"sessionsDown": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"description": "Sessions torn down during each interval."
},
"ports": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PortMetrics"
},
"description": "Per-port RX/TX throughput series."
}
},
"description": "GET /api/v1/metrics/history — parallel series keyed by the shared\n List<DateTime> MetricsHistoryDto.Times axis.",
"example": {
"intervalSeconds": 10,
"times": [
"2026-08-03T10:23:40Z",
"2026-08-03T10:23:50Z",
"2026-08-03T10:24:00Z"
],
"totalSessions": [
1840,
1841,
1842
],
"byEncap": {
"ipoe": [
210,
210,
211
],
"pppoeLocal": [
1418,
1419,
1419
],
"pppoeLac": [
96,
96,
96
],
"l2tp": [
116,
116,
116
]
},
"sessionsUp": [
3,
2,
4
],
"sessionsDown": [
1,
1,
3
],
"ports": [
{
"portId": 0,
"label": "MS3 NNI 2",
"rxBps": [
4182946816.0,
4190338048.0,
4176510976.0
],
"txBps": [
812304384.0,
818941952.0,
809467904.0
]
}
]
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
Schemas#
MetricsByEncap#
| Name | Type | Description |
|---|---|---|
ipoe |
Array<> | IPoE (DHCP) sessions. |
l2tp |
Array<> | LNS-terminated sessions arriving from LACs over L2TP. |
pppoeLac |
Array<> | PPPoE sessions tunnelled to a wholesale LNS (LAC role). |
pppoeLocal |
Array<> | Locally-terminated PPPoE sessions. |
MetricsHistory#
| Name | Type | Description |
|---|---|---|
byEncap |
MetricsByEncap | |
intervalSeconds |
Native sampling interval (seconds); longer ranges are downsampled. | |
ports |
Array<PortMetrics> | Per-port RX/TX throughput series. |
sessionsDown |
Array<> | Sessions torn down during each interval. |
sessionsUp |
Array<> | Sessions established during each interval. |
times |
Array<string(date-time)> | UTC sample timestamps; every other array aligns to this axis. |
totalSessions |
Array<> | Active session count per sample. |
PortMetrics#
| Name | Type | Description |
|---|---|---|
label |
string | Operator-friendly label from config (label/ifname/PCI). |
portId |
Data-plane port id (subscriber interfaces first, then network interfaces). | |
rxBps |
Array<> | Received bits/second per sample. |
txBps |
Array<> | Transmitted bits/second per sample. |
ProblemDetails#
| Name | Type | Description |
|---|---|---|
detail |
string | null | |
instance |
string | null | |
status |
||
title |
string | null | |
type |
string | null |
Security schemes#
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerToken | http | bearer | Named API token — the recommended credential for automation. See Authentication in the API overview. |
| sessionCookie | apiKey | Interactive session cookie used by the bundled web UI. Not the integration path for API clients — use a bearer token. See Authentication in the API overview. |
Tags#
| Name | Description |
|---|---|
| Metrics | The Prometheus scrape endpoint, and the time-series history behind the dashboard charts. |