Skip to content

Metrics#

Time-series metrics for dashboards: session counts and per-port throughput.

1 operation. 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:

Authorization: Bearer bngtok_…

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.

NetavoBNG Management API v1#

Contact: Netavo

Metrics#

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 Time-series metrics for dashboards: session counts and per-port throughput.