Sessions#
Live subscriber sessions: list/filter, detail with traffic counters, high-resolution live rates, and force-disconnect.
12 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#
Contact: Netavo
Sessions#
GET /api/v1/sessions#
List active sessions (filtered, newest first, paged).
Description
All filters combine with AND. String filters are case-insensitive; username and
ip are prefix/substring matches, the rest are exact. 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. |
encap |
query | string | No | Access encapsulation: ipoe | pppoe-local | pppoe-lac | l2tp | l2tp-lts. | |
ip |
query | string | No | Prefix match on the assigned IPv4 or IPv6 WAN address. | |
limit |
query | 100 | No | Page size, clamped to 1–500 (default 100). | |
nni |
query | string | No | Exact access NNI key the session's circuit was matched on. | |
offset |
query | 0 | No | Items to skip from the start of the (filtered, sorted) result. | |
port |
query | No | Subscriber-facing data-plane port id (excludes LNS-terminated sessions). | ||
type |
query | string | No | Session type, e.g. "ipoe" or "ppp". | |
unclaimed |
query | boolean | No | true returns only unclaimed (guest) sessions: circuits on an access NNI that were admitted by the NNI's default row and have no line yet. Each item then also carries its traffic totals. | |
username |
query | string | No | Substring match on the subscriber username. | |
vrf |
query | string | No | Exact VRF name ("default" for the global table). | |
walledGarden |
query | boolean | No | true returns only walled-garden sessions. |
Responses
{
"total": 1842,
"offset": 0,
"items": [
{
"id": 40213,
"type": "ppp",
"encap": "pppoe-local",
"username": "alice@example.net",
"subscriberReference": "FTTP000777",
"displayName": "alice@example.net",
"ipv4": "100.64.12.37",
"ipv6": "2001:db8:64:12::1",
"vrf": "residential",
"mac": "a4:2b:8c:11:9f:03",
"svlan": 101,
"vlan": 1337,
"plan": "fibre-900",
"walledGarden": false,
"unclaimed": false,
"serviceState": "Active",
"nni": null,
"presentedUsername": null,
"bytesIn": null,
"bytesOut": null,
"uptimeSeconds": 86412.538912
}
]
}
Schema of the response body
{
"required": [
"total",
"offset",
"items"
],
"type": "object",
"properties": {
"total": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Total sessions matching the filters (before paging).",
"format": "int32"
},
"offset": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The offset this page was taken at.",
"format": "int32"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SessionSummary"
},
"description": "The page of session summaries, newest session first."
}
},
"description": "GET /api/v1/sessions — one page of the filtered session list.",
"example": {
"total": 1842,
"offset": 0,
"items": [
{
"id": 40213,
"type": "ppp",
"encap": "pppoe-local",
"username": "alice@example.net",
"subscriberReference": "FTTP000777",
"displayName": "alice@example.net",
"ipv4": "100.64.12.37",
"ipv6": "2001:db8:64:12::1",
"vrf": "residential",
"mac": "a4:2b:8c:11:9f:03",
"svlan": 101,
"vlan": 1337,
"plan": "fibre-900",
"walledGarden": false,
"unclaimed": false,
"serviceState": "Active",
"nni": null,
"presentedUsername": null,
"bytesIn": null,
"bytesOut": null,
"uptimeSeconds": 86412.538912
}
]
}
}
{
"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"
}
}
POST /api/v1/sessions/coa#
Change a live session's authorization (HTTP CoA).
Description
The same power as a RADIUS CoA-Request, without a RADIUS client, shared secret or UDP 3799
reachability — so it works whatever auth.driver is, including the database driver SIM
subscribers use. Name the session with exactly one selector.
state uses the SubscriberServiceState names, not the RADIUS vocabulary: Blocked means
the data plane drops the subscriber's traffic while the session stays up, and Restricted
means the walled garden. (Over RADIUS, blocked deliberately means the walled garden for
Splynx compatibility; the API does not inherit that trap.)
Idempotent: re-applying the state a session already has returns 200 with an empty changed
and emits no event or accounting interim. A state or rate change emits an immediate interim
through whichever accounting driver is configured, so usage can be closed off at the moment
of the change. Requires the operator role (or above); local appliance only — the fleet proxy
is GET-only.
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. |
Request body
{
"selector": {
"username": "278773001210379"
},
"state": "Blocked",
"rates": {
"downKbps": 0,
"upKbps": 0
},
"sessionTimeoutSeconds": null,
"idleTimeoutSeconds": null,
"vrfName": null,
"reason": "data-allowance-exhausted"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"type": "object",
"properties": {
"selector": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/SessionSelector"
}
]
},
"state": {
"type": "string",
"description": "Active, Restricted (walled garden) or Blocked (traffic dropped, session stays up).",
"nullable": true
},
"rates": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/SessionRates"
}
]
},
"sessionTimeoutSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "New session timeout, or null to leave it.",
"format": "uint32",
"nullable": true
},
"idleTimeoutSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "New idle timeout, or null to leave it.",
"format": "uint32",
"nullable": true
},
"vrfName": {
"type": "string",
"description": "Move the session to this VRF; omit to keep the current one.",
"nullable": true
},
"reason": {
"type": "string",
"description": "Free text recorded on the session event and the audit log.",
"nullable": true
}
},
"description": "POST /api/v1/sessions/coa — change a live session's authorization.",
"example": {
"selector": {
"username": "278773001210379"
},
"state": "Blocked",
"rates": {
"downKbps": 0,
"upKbps": 0
},
"sessionTimeoutSeconds": null,
"idleTimeoutSeconds": null,
"vrfName": null,
"reason": "data-allowance-exhausted"
}
}
Responses
{
"sessionId": 40213,
"username": "278773001210379",
"changed": [
"serviceState"
],
"state": "Blocked",
"status": "applied"
}
Schema of the response body
{
"required": [
"sessionId",
"username",
"changed",
"state",
"status"
],
"type": "object",
"properties": {
"sessionId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The session acted on.",
"format": "uint32"
},
"username": {
"type": "string",
"description": "Its subscriber."
},
"changed": {
"type": "array",
"items": {
"type": "string"
},
"description": "The fields actually changed — empty when the session already matched."
},
"state": {
"type": "string",
"description": "The session's service state after the change."
},
"status": {
"type": "string",
"description": "applied, unchanged or disconnected."
}
},
"description": "The outcome of an HTTP CoA or disconnect.",
"example": {
"sessionId": 40213,
"username": "278773001210379",
"changed": [
"serviceState"
],
"state": "Blocked",
"status": "applied"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
POST /api/v1/sessions/disconnect#
Disconnect a live session by selector (HTTP Disconnect-Request).
Description
The selector form of DELETE /api/v1/sessions/{id}, for callers that know a
subscriber by username or address rather than by our session id. Requires the operator role
(or above); local appliance only.
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. |
Request body
{
"username": "278773001210379",
"sessionId": null,
"acctSessionId": null,
"framedIp": null,
"reason": "data-allowance-exhausted"
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"type": "object",
"properties": {
"sessionId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Our session id, as the session list prints it.",
"format": "uint32",
"nullable": true
},
"username": {
"type": "string",
"description": "The subscriber's username — the IMSI for a SIM.",
"nullable": true
},
"acctSessionId": {
"type": "string",
"description": "The session's RADIUS Acct-Session-Id, exactly as accounting reports it\n (`yyyyMMddHHmmssfff-XXXXXXXX`). It names one session: an id from a session that has\n ended matches nothing, even when its slot is in use again.",
"nullable": true
},
"framedIp": {
"type": "string",
"description": "The session's assigned IPv4.",
"nullable": true
},
"reason": {
"type": "string",
"description": "Free text recorded on the session event and the audit log.",
"nullable": true
}
},
"description": "Which live session to act on — exactly one of the identifying fields.",
"example": {
"username": "278773001210379",
"sessionId": null,
"acctSessionId": null,
"framedIp": null,
"reason": "data-allowance-exhausted"
}
}
Responses
{
"sessionId": 40213,
"username": "278773001210379",
"changed": [
"serviceState"
],
"state": "Blocked",
"status": "applied"
}
Schema of the response body
{
"required": [
"sessionId",
"username",
"changed",
"state",
"status"
],
"type": "object",
"properties": {
"sessionId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The session acted on.",
"format": "uint32"
},
"username": {
"type": "string",
"description": "Its subscriber."
},
"changed": {
"type": "array",
"items": {
"type": "string"
},
"description": "The fields actually changed — empty when the session already matched."
},
"state": {
"type": "string",
"description": "The session's service state after the change."
},
"status": {
"type": "string",
"description": "applied, unchanged or disconnected."
}
},
"description": "The outcome of an HTTP CoA or disconnect.",
"example": {
"sessionId": 40213,
"username": "278773001210379",
"changed": [
"serviceState"
],
"state": "Blocked",
"status": "applied"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
POST /api/v1/sessions/reapply#
Re-apply the CGN limits of every live session.
Description
The bulk form of POST /api/v1/sessions/{id}/reapply, over every live CG-NAT
binding or those of one inside VRF. Each binding is rewritten in place only when its limits
differ from its group's; the response counts them and lists the ones that failed (each
keeps its limits). Like the CLI request subscribers reapply all [vrf]. Requires the
operator role (or above); local appliance only.
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. |
Request body
Responses
{
"changed": 1,
"unchanged": 0,
"failed": 0,
"bindings": [
{
"bindingIndex": 10427,
"outcome": "changed",
"portCap": 4096,
"setupsPerSec": 1000,
"error": null
}
]
}
Schema of the response body
{
"required": [
"changed",
"unchanged",
"failed",
"bindings"
],
"type": "object",
"properties": {
"changed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings rewritten with their group's current limits.",
"format": "int32"
},
"unchanged": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings that already had them (nothing written).",
"format": "int32"
},
"failed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings the data plane did not take the rewrite for; each keeps its\n limits.",
"format": "int32"
},
"bindings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnReapplyBinding"
},
"description": "For one session, each of its bindings; for every session, only the\n ones that failed."
}
},
"description": "Result of re-applying CGN limits (POST /api/v1/sessions/{id}/reapply and\n POST /api/v1/sessions/reapply).",
"example": {
"changed": 1,
"unchanged": 0,
"failed": 0,
"bindings": [
{
"bindingIndex": 10427,
"outcome": "changed",
"portCap": 4096,
"setupsPerSec": 1000,
"error": null
}
]
}
}
{
"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"
}
}
{
"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/sessions/sparklines#
Two-hour throughput sparklines for a page of sessions.
Description
For the session list: per requested session, 60 two-minute points of its
subscriber's download rate and of its upload rate over the last two hours, oldest first,
null where there is no data. The two series are on the same points and have their gaps in
the same places, so they can be drawn against one scale. A separate call rather than a field of the list so the list — polled every few
seconds — stays cheap; a sparkline changes once a minute, so fetch it once
a minute. Sessions that do not exist are omitted. When subscriber-history enabled is off,
enabled is false and items is empty. 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. |
ids |
query | string | No | Comma-separated session ids, at most 500 (the list's largest page). |
Responses
{
"enabled": true,
"stepSeconds": 120,
"items": [
{
"id": 40213,
"downBps": [
null,
18422138,
214880994
],
"upBps": [
null,
902144,
17980413
]
}
]
}
Schema of the response body
{
"required": [
"enabled",
"stepSeconds",
"items"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "False when the appliance keeps no history; Items is\n then empty."
},
"stepSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Width of one point (120: two minutes, 60 points = 2 h).",
"format": "int32"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SessionSparkline"
},
"description": "One entry per requested session that exists."
}
},
"description": "GET /api/v1/sessions/sparklines — a short download and upload series per session, for\n the session list.",
"example": {
"enabled": true,
"stepSeconds": 120,
"items": [
{
"id": 40213,
"downBps": [
null,
18422138,
214880994
],
"upBps": [
null,
902144,
17980413
]
}
]
}
}
{
"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"
}
}
{
"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/sessions/summary#
Session counts for dashboard tiles.
Description
Returns the total number of active subscriber sessions plus breakdowns by session type, access encapsulation, subscriber-facing port, and VRF, and the number of sessions currently in the walled garden. Cheap to poll; 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. |
Responses
{
"total": 1842,
"byType": {
"ppp": 1503,
"ipoe": 339
},
"byEncap": {
"pppoe-local": 1200,
"l2tp": 303,
"ipoe": 339
},
"byPort": [
{
"portId": 0,
"label": "xe-0/0/0",
"count": 1503
}
],
"byVrf": {
"residential": 1789,
"default": 53
},
"walledGarden": 7,
"unclaimed": 3
}
Schema of the response body
{
"required": [
"total",
"byType",
"byEncap",
"byPort",
"byVrf",
"walledGarden"
],
"type": "object",
"properties": {
"total": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Number of active subscriber sessions.",
"format": "int32"
},
"byType": {
"type": "object",
"additionalProperties": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"description": "Session count per session type (e.g. \"ipoe\", \"ppp\")."
},
"byEncap": {
"type": "object",
"additionalProperties": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"description": "Session count per access encapsulation (ipoe | pppoe-local | pppoe-lac | l2tp | l2tp-lts)."
},
"byPort": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PortSessionCount"
},
"description": "Session count per subscriber-facing port (LNS-terminated sessions excluded)."
},
"byVrf": {
"type": "object",
"additionalProperties": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32"
},
"description": "Session count per VRF; sessions in the global table count under \"default\"."
},
"walledGarden": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Number of sessions currently redirected to the walled garden.",
"format": "int32"
},
"unclaimed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Number of unclaimed (guest) sessions: circuits on an access NNI admitted by the NNI's default row, with no line yet.",
"format": "int32",
"default": 0
}
},
"description": "GET /api/v1/sessions/summary — dashboard counts over the active sessions.",
"example": {
"total": 1842,
"byType": {
"ppp": 1503,
"ipoe": 339
},
"byEncap": {
"pppoe-local": 1200,
"l2tp": 303,
"ipoe": 339
},
"byPort": [
{
"portId": 0,
"label": "xe-0/0/0",
"count": 1503
}
],
"byVrf": {
"residential": 1789,
"default": 53
},
"walledGarden": 7,
"unclaimed": 3
}
}
{
"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/sessions/{id}#
Full detail for one active session.
Description
Includes addressing, VLANs, service plan, live data-plane traffic counters and — for L2TP-carried sessions — the tunnel endpoints. Fields that don't apply to the session's encapsulation are null. 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. |
id |
path | No | The BNG session id (from the list endpoint). |
Responses
{
"id": 40213,
"type": "ppp",
"encap": "pppoe-local",
"username": "alice@example.net",
"subscriberReference": "FTTP000777",
"displayName": "alice@example.net",
"subscriberKey": "svc:6f1c2a0e-58b4-4d6e-9a0f-0d6b6f0c7a11",
"serviceId": "6f1c2a0e-58b4-4d6e-9a0f-0d6b6f0c7a11",
"ipv4": "100.64.12.37",
"ipv6": "2001:db8:64:12::1",
"ipv6PdPrefix": "2001:db8:1234:5600::/56",
"vrf": "residential",
"mac": "a4:2b:8c:11:9f:03",
"svlan": 101,
"vlan": 1337,
"portId": 0,
"portLabel": "xe-0/0/0",
"plan": "fibre-900",
"walledGarden": false,
"unclaimed": false,
"serviceState": "Active",
"nni": null,
"presentedUsername": null,
"pppoeSessionId": 4118,
"additionalRoutes": [
"198.51.100.64/29"
],
"routesNotInstalled": [],
"cgnBindings": [
{
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"source": "session",
"portBlocks": [
{
"portStart": 21504,
"portEnd": 22015,
"allocatedUtc": "2026-08-02T10:24:00Z"
},
{
"portStart": 22016,
"portEnd": 22527,
"allocatedUtc": "2026-08-03T08:02:11Z"
}
],
"chunkSize": 512,
"portCap": 4096,
"maxPortBlocks": 8,
"setupsPerSec": 100,
"createdUtc": "2026-08-02T10:24:00Z",
"usage": {
"portsUsed": 611,
"flowsActive": 640,
"flowsInbound": 3,
"flowsCreatedTotal": 182044,
"dropsPortCap": 0,
"dropsSetupRate": 0
}
}
],
"traffic": {
"bytesIn": 184320000,
"bytesOut": 2216755200,
"packetsIn": 812004,
"packetsOut": 1904321,
"dropsUrpf": 0,
"dropsRateLimit": 152
},
"createdUtc": "2026-08-02T10:24:00Z",
"lastActivityUtc": "2026-08-03T10:23:58Z",
"uptimeSeconds": 86412.538912,
"sessionTimeoutSeconds": 0,
"idleTimeoutSeconds": 1800,
"leaseSeconds": null,
"leaseRenewedUtc": null,
"leaseExpiresUtc": null,
"l2tp": null
}
Schema of the response body
{
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "BNG session id.",
"format": "uint32"
},
"type": {
"type": "string",
"description": "Session type: \"ipoe\" or \"ppp\"."
},
"encap": {
"type": "string",
"description": "Access encapsulation — drives which fields apply (requirements 21.7):\n ipoe | pppoe-local | pppoe-lac | l2tp (LNS-terminated, subscriber behind a LAC) | l2tp-lts (switched onward to another LNS)."
},
"username": {
"type": "string",
"description": "Subscriber username: the key the session is found by, always its true value."
},
"subscriberReference": {
"type": "string",
"description": "The reference of the line the session belongs to, as people know it (e.g.\n `FTTP152238`), when the subscriber source publishes one; otherwise null.",
"nullable": true
},
"displayName": {
"type": "string",
"description": "What to show as the subscriber: `subscriberReference` when there is one and\n `username` is a system-made one (`circuit:…`), otherwise `username`."
},
"subscriberKey": {
"type": "string",
"description": "The subscriber's durable identity — what the throughput history is kept under, and\n the same across reconnects. A type prefix and a value, the first that applies:\n `svc:` the AAA service id, `user:` the username (lower-cased), `cid:` the\n DHCP Option-82 circuit-id (hex), `port:` port:S-VLAN:VLAN."
},
"serviceId": {
"type": "string",
"description": "The stable subject id AAA resolved for this subscriber (the accounting partition\n key), or null when the auth driver supplied none.",
"format": "uuid",
"nullable": true
},
"ipv4": {
"type": "string",
"description": "Assigned IPv4 address, or null if IPv6-only.",
"nullable": true
},
"ipv6": {
"type": "string",
"description": "IPv6 WAN address, or null.",
"nullable": true
},
"ipv6PdPrefix": {
"type": "string",
"description": "Delegated IPv6 prefix (DHCPv6-PD), or null.",
"nullable": true
},
"vrf": {
"type": "string",
"description": "VRF carrying the session (\"default\" = global table)."
},
"mac": {
"type": "string",
"description": "Subscriber MAC address, or null when unknown.",
"nullable": true
},
"svlan": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Outer (service) VLAN id; 0 when untagged.",
"format": "uint16"
},
"vlan": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Inner (customer) VLAN id; 0 when untagged.",
"format": "uint16"
},
"portId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Data-plane port the session terminates on.",
"format": "uint8"
},
"portLabel": {
"type": "string",
"description": "Operator-friendly label for that port, or null.",
"nullable": true
},
"plan": {
"type": "string",
"description": "Service plan name, or null.",
"nullable": true
},
"walledGarden": {
"type": "boolean",
"description": "True while the session is redirected to the walled garden."
},
"unclaimed": {
"type": "boolean",
"description": "True for an unclaimed (guest) session: admitted by its access NNI's default\n row, with no line found for its circuit yet."
},
"serviceState": {
"type": "string",
"description": "What the data plane enforces for the session: `Active`, `Restricted`\n (walled garden only) or `Blocked` (all subscriber traffic dropped)."
},
"nni": {
"type": "string",
"description": "The access NNI key the session's circuit was matched on, or null.",
"nullable": true
},
"presentedUsername": {
"type": "string",
"description": "The username the CPE itself presented, when the session runs under a different\n one because it was identified by its circuit; otherwise null.",
"nullable": true
},
"pppoeSessionId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "PPPoE session id on the access side, or null for non-PPPoE sessions.",
"format": "uint16",
"nullable": true
},
"additionalRoutes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra framed routes installed for this subscriber, as \"prefix/len\" strings."
},
"routesNotInstalled": {
"type": "array",
"items": {
"type": "string"
},
"description": "Routes of this session (its own addresses or framed routes) that are NOT\n installed in FRR because the configuration itself routes the same prefix in the same\n table, as \"prefix/len\" strings; the configured route stands. Empty normally."
},
"traffic": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/SessionTraffic"
}
]
},
"cgnBindings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SessionCgnBinding"
},
"description": "The CG-NAT bindings that translate this session's IPv4: the one created for\n the session and any auto-learned binding for the same inside address and VRF.\n `null` when the session is not translated (or CG-NAT is not running) - the key is\n present with a null value, as this record's other optional members are (`nni`,\n `l2tp`), and never an empty list. An appliance that predates the field omits the\n key; a client should treat absent and null alike.",
"nullable": true
},
"createdUtc": {
"type": "string",
"description": "UTC time the session was established.",
"format": "date-time"
},
"lastActivityUtc": {
"type": "string",
"description": "UTC time of the last packet seen from the subscriber.",
"format": "date-time"
},
"uptimeSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"description": "Seconds since the session was established.",
"format": "double"
},
"sessionTimeoutSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "RADIUS Session-Timeout being enforced; 0 = none.",
"format": "uint32"
},
"idleTimeoutSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "RADIUS Idle-Timeout being enforced; 0 = none.",
"format": "uint32"
},
"leaseSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The DHCPv4 lease length handed to the client, in seconds - what bounds an IPoE\n session, which the client renews at half of it. Null when the session has no DHCPv4\n lease (a PPP session, a v6-only IPoE session), and for a lease restored after a\n control-plane restart, whose length is not known until the client next renews.",
"format": "int32",
"nullable": true
},
"leaseRenewedUtc": {
"type": "string",
"description": "UTC time the DHCPv4 lease was last granted or renewed. Null when there is no\n lease, and for a lease restored after a control-plane restart.",
"format": "date-time",
"nullable": true
},
"leaseExpiresUtc": {
"type": "string",
"description": "UTC time the DHCPv4 lease the client holds runs out unless it renews\n (`leaseRenewedUtc` + `leaseSeconds`). The session itself is ended a short grace\n after this. Null when the session has no DHCPv4 lease. An appliance that predates the\n three lease fields omits the keys; a client should treat absent and null alike.",
"format": "date-time",
"nullable": true
},
"l2tp": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/SessionL2tp"
}
]
}
},
"description": "GET /api/v1/sessions/{id} — full detail for one session.",
"example": {
"id": 40213,
"type": "ppp",
"encap": "pppoe-local",
"username": "alice@example.net",
"subscriberReference": "FTTP000777",
"displayName": "alice@example.net",
"subscriberKey": "svc:6f1c2a0e-58b4-4d6e-9a0f-0d6b6f0c7a11",
"serviceId": "6f1c2a0e-58b4-4d6e-9a0f-0d6b6f0c7a11",
"ipv4": "100.64.12.37",
"ipv6": "2001:db8:64:12::1",
"ipv6PdPrefix": "2001:db8:1234:5600::/56",
"vrf": "residential",
"mac": "a4:2b:8c:11:9f:03",
"svlan": 101,
"vlan": 1337,
"portId": 0,
"portLabel": "xe-0/0/0",
"plan": "fibre-900",
"walledGarden": false,
"unclaimed": false,
"serviceState": "Active",
"nni": null,
"presentedUsername": null,
"pppoeSessionId": 4118,
"additionalRoutes": [
"198.51.100.64/29"
],
"routesNotInstalled": [],
"cgnBindings": [
{
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"source": "session",
"portBlocks": [
{
"portStart": 21504,
"portEnd": 22015,
"allocatedUtc": "2026-08-02T10:24:00Z"
},
{
"portStart": 22016,
"portEnd": 22527,
"allocatedUtc": "2026-08-03T08:02:11Z"
}
],
"chunkSize": 512,
"portCap": 4096,
"maxPortBlocks": 8,
"setupsPerSec": 100,
"createdUtc": "2026-08-02T10:24:00Z",
"usage": {
"portsUsed": 611,
"flowsActive": 640,
"flowsInbound": 3,
"flowsCreatedTotal": 182044,
"dropsPortCap": 0,
"dropsSetupRate": 0
}
}
],
"traffic": {
"bytesIn": 184320000,
"bytesOut": 2216755200,
"packetsIn": 812004,
"packetsOut": 1904321,
"dropsUrpf": 0,
"dropsRateLimit": 152
},
"createdUtc": "2026-08-02T10:24:00Z",
"lastActivityUtc": "2026-08-03T10:23:58Z",
"uptimeSeconds": 86412.538912,
"sessionTimeoutSeconds": 0,
"idleTimeoutSeconds": 1800,
"leaseSeconds": null,
"leaseRenewedUtc": null,
"leaseExpiresUtc": null,
"l2tp": null
}
}
{
"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"
}
}
{
"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"
}
}
DELETE /api/v1/sessions/{id}#
Force-disconnect a session.
Description
Tears the session down exactly like the CLI request subscribers disconnect
command: the subscriber is disconnected, accounting Stop is emitted, and the action is
written to the audit log with the acting identity. Requires the operator role (or above);
local appliance only — not available through the fleet proxy.
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. |
id |
path | No | The BNG session id to disconnect. |
Responses
Schema of the response body
{
"required": [
"status",
"id",
"username"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"disconnected\"."
},
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The disconnected session's id.",
"format": "uint32"
},
"username": {
"type": "string",
"description": "The disconnected subscriber's username."
}
},
"description": "DELETE /api/v1/sessions/{id} result.",
"example": {
"status": "disconnected",
"id": 40213,
"username": "alice@example.net"
}
}
{
"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"
}
}
{
"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/sessions/{id}/history#
The last 24 hours of throughput for a session's subscriber.
Description
Download and upload rate of the subscriber who owns the session — keyed on the
subscriber's identity (subscriberKey in the session detail), not the session, so the
series continues across a reconnect and a control-plane restart. Sampled once a minute and
kept on the appliance's disk for 24 hours.
`range=2h` returns 120 one-minute buckets; `range=24h` returns 288 five-minute buckets, each
the mean of its minutes with the highest minute as the peak (at one-minute resolution the
peak equals the mean). Every bucket of the range is present, oldest first, as parallel
arrays on the `times` axis (bucket start). **A bucket with no data is `null`** in every
series: the subscriber was offline, or the appliance was not sampling. An idle subscriber
is `0`, not `null`.
An operational view, not usage: rates are rounded and nothing here is used for accounting.
When `subscriber-history enabled` is off, `enabled` is false and the series are empty.
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. |
id |
path | No | The BNG session id. | ||
range |
query | string | 24h | No | "2h" or "24h" (default; anything else is treated as 24h). |
Responses
{
"enabled": true,
"subscriberKey": "user:alice@example.net",
"range": "24h",
"stepSeconds": 300,
"times": [
"2026-08-03T10:15:00Z",
"2026-08-03T10:20:00Z",
"2026-08-03T10:25:00Z"
],
"downBps": [
214880994,
null,
18422138
],
"upBps": [
17980413,
null,
902144
],
"downPeakBps": [
402118730,
null,
31250112
],
"upPeakBps": [
22140982,
null,
1204880
]
}
Schema of the response body
{
"required": [
"enabled",
"subscriberKey",
"range",
"stepSeconds",
"times",
"downBps",
"upBps",
"downPeakBps",
"upPeakBps"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "False when the appliance keeps no history (`subscriber-history enabled`\n is off); the series are then empty."
},
"subscriberKey": {
"type": "string",
"description": "The identity the history is kept under (see the session detail)."
},
"range": {
"type": "string",
"description": "The range returned: \"2h\" or \"24h\"."
},
"stepSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Width of one bucket: 60 for 2h, 300 for 24h.",
"format": "int32"
},
"times": {
"type": "array",
"items": {
"type": "string",
"format": "date-time"
},
"description": "UTC start of each bucket."
},
"downBps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double",
"nullable": true
},
"description": "Mean bits/second sent to the subscriber (download) in the bucket."
},
"upBps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double",
"nullable": true
},
"description": "Mean bits/second received from the subscriber (upload) in the bucket."
},
"downPeakBps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double",
"nullable": true
},
"description": "Highest one-minute download average inside the bucket."
},
"upPeakBps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double",
"nullable": true
},
"description": "Highest one-minute upload average inside the bucket."
}
},
"description": "GET /api/v1/sessions/{id}/history — a subscriber's throughput as parallel series on\n the List<DateTime> SubscriberHistoryDto.Times axis, oldest bucket first. A bucket with no data is null in every\n series.",
"example": {
"enabled": true,
"subscriberKey": "user:alice@example.net",
"range": "24h",
"stepSeconds": 300,
"times": [
"2026-08-03T10:15:00Z",
"2026-08-03T10:20:00Z",
"2026-08-03T10:25:00Z"
],
"downBps": [
214880994,
null,
18422138
],
"upBps": [
17980413,
null,
902144
],
"downPeakBps": [
402118730,
null,
31250112
],
"upPeakBps": [
22140982,
null,
1204880
]
}
}
{
"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"
}
}
{
"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/sessions/{id}/live#
High-resolution live traffic rates for one session.
Description
2-second samples for the session-detail live chart (requirements: watched
sessions). Polling this endpoint IS the watch keepalive — the appliance samples a session
only while something polls it, so the first call may return an empty series. Returns
parallel arrays keyed by the shared times axis. Fleet-proxyable (watching a remote
appliance's session registers the watch on that appliance).
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. |
id |
path | No | The BNG session id. |
Responses
{
"intervalSeconds": 5,
"times": [
"2026-08-03T10:24:00Z",
"2026-08-03T10:24:05Z"
],
"rxBps": [
18422137.6,
17980412.8
],
"txBps": [
214880993.6,
221304476.8
],
"rxPps": [
2140.4,
2098.2
],
"txPps": [
19040.8,
19422.6
]
}
Schema of the response body
{
"required": [
"intervalSeconds",
"times",
"rxBps",
"txBps",
"rxPps",
"txPps"
],
"type": "object",
"properties": {
"intervalSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Sampling interval of the series (seconds).",
"format": "int32"
},
"times": {
"type": "array",
"items": {
"type": "string",
"format": "date-time"
},
"description": "UTC sample timestamps; all rate arrays align to this axis."
},
"rxBps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double"
},
"description": "Bits/second received from the subscriber (upload)."
},
"txBps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double"
},
"description": "Bits/second sent to the subscriber (download)."
},
"rxPps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double"
},
"description": "Packets/second received from the subscriber."
},
"txPps": {
"type": "array",
"items": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"format": "double"
},
"description": "Packets/second sent to the subscriber."
}
},
"description": "GET /api/v1/sessions/{id}/live — parallel rate series keyed by the shared\n List<DateTime> SessionLiveRatesDto.Times axis. Arrays are empty until the watch has collected samples.",
"example": {
"intervalSeconds": 5,
"times": [
"2026-08-03T10:24:00Z",
"2026-08-03T10:24:05Z"
],
"rxBps": [
18422137.6,
17980412.8
],
"txBps": [
214880993.6,
221304476.8
],
"rxPps": [
2140.4,
2098.2
],
"txPps": [
19040.8,
19422.6
]
}
}
{
"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"
}
}
{
"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"
}
}
POST /api/v1/sessions/{id}/reapply#
Re-apply a session's CGN limits.
Description
Moves the session's CG-NAT bindings onto the port cap, new-flow rate and binding
timeout its CGN IP group has now, in place: the same public address and port blocks, and
the translations are kept. A committed change to a group's limits applies to new bindings
only until this (or POST /api/v1/sessions/reapply) is run. CGN limits only — rates and
shaping change through POST /api/v1/sessions/coa. A lowered cap keeps the blocks already
held and stops growth. Like the CLI request subscribers reapply id. Requires the operator
role (or above); local appliance only.
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. |
id |
path | No | The BNG session id. |
Responses
{
"changed": 1,
"unchanged": 0,
"failed": 0,
"bindings": [
{
"bindingIndex": 10427,
"outcome": "changed",
"portCap": 4096,
"setupsPerSec": 1000,
"error": null
}
]
}
Schema of the response body
{
"required": [
"changed",
"unchanged",
"failed",
"bindings"
],
"type": "object",
"properties": {
"changed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings rewritten with their group's current limits.",
"format": "int32"
},
"unchanged": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings that already had them (nothing written).",
"format": "int32"
},
"failed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings the data plane did not take the rewrite for; each keeps its\n limits.",
"format": "int32"
},
"bindings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnReapplyBinding"
},
"description": "For one session, each of its bindings; for every session, only the\n ones that failed."
}
},
"description": "Result of re-applying CGN limits (POST /api/v1/sessions/{id}/reapply and\n POST /api/v1/sessions/reapply).",
"example": {
"changed": 1,
"unchanged": 0,
"failed": 0,
"bindings": [
{
"bindingIndex": 10427,
"outcome": "changed",
"portCap": 4096,
"setupsPerSec": 1000,
"error": null
}
]
}
}
{
"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"
}
}
{
"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/sessions/{id}/translations#
A session's live CG-NAT translations.
Description
One row per translation (flow) the data plane holds for the session's CG-NAT
binding: protocol, the inside address and port, the public port, the remote address and
port, who opened it, and how long until it is released — ordered by protocol, then public
port. A binding can hold a few thousand, so the answer is a page: matched is how many
rows the filter leaves and offset / limit move through them; total is every
translation of the binding. protocol and port filter before paging.
The rows are read from the data plane on each call (a query its control thread answers
from the binding's own list; nothing on the packet path), so this is rate-limited as a
heavy read and is meant to be asked for, not polled. Translations come and go while they
are read: a row may be gone by the time it is shown. The data plane keeps no byte or
packet count per translation.
**Operator role or above** — the rows name who the subscriber is communicating with,
which the session's other reads do not — and each read is audited with the acting
identity. 404 when the session is not translated; 503 when the data plane cannot be
asked (not running, a build that predates this, or a development host's mock data 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. |
binding |
query | No | Which of the session's bindings, by index (from `cgnBindings` in the session detail). Omitted: the session's first — nearly every session has one. | ||
id |
path | No | The BNG session id. | ||
limit |
query | 200 | No | Page size, clamped to 1–1000 (default 200). | |
offset |
query | 0 | No | Rows to skip (default 0). | |
port |
query | No | Only translations whose inside, public or remote port is this. | ||
protocol |
query | string | No | Only this protocol: `tcp`, `udp` or `icmp`. |
Responses
{
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"total": 412,
"matched": 2,
"offset": 0,
"limit": 200,
"complete": true,
"items": [
{
"protocol": "tcp",
"insideIp": "100.64.12.37",
"insidePort": 51844,
"publicPort": 21507,
"remoteIp": "198.51.100.20",
"remotePort": 443,
"direction": "outbound",
"hairpin": false,
"state": "established",
"ageSeconds": 912,
"idleSeconds": 4,
"timeoutSeconds": 7440,
"expiresInSeconds": 7436
},
{
"protocol": "udp",
"insideIp": "100.64.12.37",
"insidePort": 40122,
"publicPort": 21611,
"remoteIp": "192.0.2.53",
"remotePort": 53,
"direction": "outbound",
"hairpin": false,
"state": null,
"ageSeconds": 11,
"idleSeconds": 11,
"timeoutSeconds": 30,
"expiresInSeconds": 19
}
]
}
Schema of the response body
{
"required": [
"bindingIndex",
"group",
"insideVrf",
"insideIp",
"publicIp",
"total",
"matched",
"offset",
"limit",
"complete",
"items"
],
"type": "object",
"properties": {
"bindingIndex": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The binding the translations belong to.",
"format": "uint32"
},
"group": {
"type": "string",
"description": "CGN IP group of the binding."
},
"insideVrf": {
"type": "string",
"description": "Inside VRF of the subscriber (\"default\" = global table)."
},
"insideIp": {
"type": "string",
"description": "The subscriber's inside IPv4 address."
},
"publicIp": {
"type": "string",
"description": "The public IPv4 address every translation here leaves from."
},
"total": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Translations the data plane holds for the binding, before any filter.",
"format": "int32"
},
"matched": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Of those, how many match the filter — what `offset` and `limit` page through.",
"format": "int32"
},
"offset": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Rows skipped.",
"format": "int32"
},
"limit": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Page size in force.",
"format": "int32"
},
"complete": {
"type": "boolean",
"description": "False when the binding has more translations than one listing reads; the rows are right but are not all of them."
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnTranslation"
},
"description": "The page, ordered by protocol, then public port, then remote address and port."
}
},
"description": "A page of one CG-NAT binding's live translations\n (`GET /api/v1/sessions/{id}/translations`).",
"example": {
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"total": 412,
"matched": 2,
"offset": 0,
"limit": 200,
"complete": true,
"items": [
{
"protocol": "tcp",
"insideIp": "100.64.12.37",
"insidePort": 51844,
"publicPort": 21507,
"remoteIp": "198.51.100.20",
"remotePort": 443,
"direction": "outbound",
"hairpin": false,
"state": "established",
"ageSeconds": 912,
"idleSeconds": 4,
"timeoutSeconds": 7440,
"expiresInSeconds": 7436
},
{
"protocol": "udp",
"insideIp": "100.64.12.37",
"insidePort": 40122,
"publicPort": 21611,
"remoteIp": "192.0.2.53",
"remotePort": 53,
"direction": "outbound",
"hairpin": false,
"state": null,
"ageSeconds": 11,
"idleSeconds": 11,
"timeoutSeconds": 30,
"expiresInSeconds": 19
}
]
}
}
{
"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"
}
}
{
"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"
}
}
{
"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#
CgnReapplyBinding#
| Name | Type | Description |
|---|---|---|
bindingIndex |
The binding (as in /api/v1/cgn/bindings). | |
error |
string | null | Why the rewrite failed; null otherwise. |
outcome |
string | "changed", "unchanged" or "failed". |
portCap |
The port cap the binding has now. | |
setupsPerSec |
The new-flow rate limit the binding has now (0 = unlimited). |
CgnReapplyRequest#
| Name | Type | Description |
|---|---|---|
vrf |
string | null | Only the bindings of this inside VRF ("default" for the global table); null or omitted for every binding. |
CgnReapplyResult#
| Name | Type | Description |
|---|---|---|
bindings |
Array<CgnReapplyBinding> | For one session, each of its bindings; for every session, only the ones that failed. |
changed |
Bindings rewritten with their group's current limits. | |
failed |
Bindings the data plane did not take the rewrite for; each keeps its limits. | |
unchanged |
Bindings that already had them (nothing written). |
CgnTranslation#
| Name | Type | Description |
|---|---|---|
ageSeconds |
Seconds since it was created. | |
direction |
string | "outbound": the subscriber opened it. "inbound": a remote host opened it, to a port the subscriber already had mapped. |
expiresInSeconds |
Seconds until it may be released if nothing more passes; 0 = due at the next sweep, which can take up to a minute more. | |
hairpin |
boolean | True when the remote is another subscriber's public address on this appliance. |
idleSeconds |
Seconds since a packet last refreshed it (one-second resolution). | |
insideIp |
string | The inside host (the subscriber's address, or one behind its routed prefix). |
insidePort |
The inside port; for ICMP, the echo identifier. | |
protocol |
string | "tcp", "udp" or "icmp". |
publicPort |
The public port (ICMP: identifier) it is translated to. | |
remoteIp |
string | The remote address. |
remotePort |
The remote port (0 for ICMP). | |
state |
string | null | TCP only: "opening", "established" or "closing"; null for UDP and ICMP. |
timeoutSeconds |
The idle timeout that applies to it as it stands. |
CgnTranslations#
| Name | Type | Description |
|---|---|---|
bindingIndex |
The binding the translations belong to. | |
complete |
boolean | False when the binding has more translations than one listing reads; the rows are right but are not all of them. |
group |
string | CGN IP group of the binding. |
insideIp |
string | The subscriber's inside IPv4 address. |
insideVrf |
string | Inside VRF of the subscriber ("default" = global table). |
items |
Array<CgnTranslation> | The page, ordered by protocol, then public port, then remote address and port. |
limit |
Page size in force. | |
matched |
Of those, how many match the filter — what `offset` and `limit` page through. | |
offset |
Rows skipped. | |
publicIp |
string | The public IPv4 address every translation here leaves from. |
total |
Translations the data plane holds for the binding, before any filter. |
PortSessionCount#
| Name | Type | Description |
|---|---|---|
count |
Active sessions on this port. | |
label |
string | null | Operator-friendly port label from config (label/ifname/PCI), or null. |
portId |
Data-plane port id (subscriber interfaces first, then network interfaces). |
ProblemDetails#
| Name | Type | Description |
|---|---|---|
detail |
string | null | |
instance |
string | null | |
status |
||
title |
string | null | |
type |
string | null |
SessionCgnBinding#
| Name | Type | Description |
|---|---|---|
bindingIndex |
Stable index of the binding (as in `/api/v1/cgn/bindings`). | |
blocks |
||
blocksNotRead |
string | null | Why `blocks` is null: no data plane to ask, its heartbeat is stale, or it did not answer in time. |
chunkSize |
Ports per block. | |
createdUtc |
string(date-time) | UTC time the binding was created. |
group |
string | CGN IP group the public address came from. |
insideIp |
string | The subscriber's inside IPv4 address. |
insideVrf |
string | Inside VRF of the subscriber ("default" = global table). |
maxPortBlocks |
The most blocks this binding may grow to: the port cap in blocks, at most 8. A binding whose cap was lowered after it grew can hold more; it keeps them and is granted no more. | |
portBlocks |
Array<SessionCgnPortBlock> | Every port block the binding holds, in the order they were granted. |
portCap |
The most ports this subscriber may use. | |
publicIp |
string | Public IPv4 address the subscriber is translated to. |
setupsPerSec |
New-flow rate limit in force for the binding (flows per second). | |
source |
string | How the binding came about: "session" (created with the session) or "auto-learned" (learned from traffic). |
usage |
SessionCgnBlocks#
| Name | Type | Description |
|---|---|---|
disagreement |
string | null | Why the data plane's binding is not the control plane's record (another block list, say); null when they agree. |
empty |
Blocks with no port in use, wherever they are. | |
held |
Port blocks the data plane holds for the binding. | |
inUse |
Array<> | Ports in use in each block, lowest block first. Read while ports are claimed and released, so a count can be off by the ones in flight. |
reclaimable |
Empty blocks at the top of the list, which a reclaim could give back. 0 while the control and data plane disagree. |
SessionCgnPortBlock#
| Name | Type | Description |
|---|---|---|
allocatedUtc |
string(date-time) | UTC time the block was granted. |
portEnd |
Last public port of the block (inclusive). | |
portStart |
First public port of the block. |
SessionCgnUsage#
| Name | Type | Description |
|---|---|---|
dropsPortCap |
Packets dropped because the subscriber was at its port cap. | |
dropsSetupRate |
Packets dropped by the new-flow rate limit. | |
flowsActive |
Translations (flows) active now. | |
flowsCreatedTotal |
Flows created since the binding was made. | |
flowsInbound |
Of those, flows opened from outside. | |
portsUsed |
Public ports in use now. |
SessionCoaRequest#
| Name | Type | Description |
|---|---|---|
idleTimeoutSeconds |
New idle timeout, or null to leave it. | |
rates |
||
reason |
string | null | Free text recorded on the session event and the audit log. |
selector |
||
sessionTimeoutSeconds |
New session timeout, or null to leave it. | |
state |
string | null | Active, Restricted (walled garden) or Blocked (traffic dropped, session stays up). |
vrfName |
string | null | Move the session to this VRF; omit to keep the current one. |
SessionCoaResult#
| Name | Type | Description |
|---|---|---|
changed |
Array<string> | The fields actually changed — empty when the session already matched. |
sessionId |
The session acted on. | |
state |
string | The session's service state after the change. |
status |
string | applied, unchanged or disconnected. |
username |
string | Its subscriber. |
SessionDetail#
| Name | Type | Description |
|---|---|---|
additionalRoutes |
Array<string> | Extra framed routes installed for this subscriber, as "prefix/len" strings. |
cgnBindings |
Array<SessionCgnBinding> | The CG-NAT bindings that translate this session's IPv4: the one created for the session and any auto-learned binding for the same inside address and VRF. `null` when the session is not translated (or CG-NAT is not running) - the key is present with a null value, as this record's other optional members are (`nni`, `l2tp`), and never an empty list. An appliance that predates the field omits the key; a client should treat absent and null alike. |
createdUtc |
string(date-time) | UTC time the session was established. |
displayName |
string | What to show as the subscriber: `subscriberReference` when there is one and `username` is a system-made one (`circuit:…`), otherwise `username`. |
encap |
string | Access encapsulation — drives which fields apply (requirements 21.7): ipoe | pppoe-local | pppoe-lac | l2tp (LNS-terminated, subscriber behind a LAC) | l2tp-lts (switched onward to another LNS). |
id |
BNG session id. | |
idleTimeoutSeconds |
RADIUS Idle-Timeout being enforced; 0 = none. | |
ipv4 |
string | null | Assigned IPv4 address, or null if IPv6-only. |
ipv6 |
string | null | IPv6 WAN address, or null. |
ipv6PdPrefix |
string | null | Delegated IPv6 prefix (DHCPv6-PD), or null. |
l2tp |
||
lastActivityUtc |
string(date-time) | UTC time of the last packet seen from the subscriber. |
leaseExpiresUtc |
string(date-time) | null | UTC time the DHCPv4 lease the client holds runs out unless it renews (`leaseRenewedUtc` + `leaseSeconds`). The session itself is ended a short grace after this. Null when the session has no DHCPv4 lease. An appliance that predates the three lease fields omits the keys; a client should treat absent and null alike. |
leaseRenewedUtc |
string(date-time) | null | UTC time the DHCPv4 lease was last granted or renewed. Null when there is no lease, and for a lease restored after a control-plane restart. |
leaseSeconds |
The DHCPv4 lease length handed to the client, in seconds - what bounds an IPoE session, which the client renews at half of it. Null when the session has no DHCPv4 lease (a PPP session, a v6-only IPoE session), and for a lease restored after a control-plane restart, whose length is not known until the client next renews. | |
mac |
string | null | Subscriber MAC address, or null when unknown. |
nni |
string | null | The access NNI key the session's circuit was matched on, or null. |
plan |
string | null | Service plan name, or null. |
portId |
Data-plane port the session terminates on. | |
portLabel |
string | null | Operator-friendly label for that port, or null. |
pppoeSessionId |
PPPoE session id on the access side, or null for non-PPPoE sessions. | |
presentedUsername |
string | null | The username the CPE itself presented, when the session runs under a different one because it was identified by its circuit; otherwise null. |
routesNotInstalled |
Array<string> | Routes of this session (its own addresses or framed routes) that are NOT installed in FRR because the configuration itself routes the same prefix in the same table, as "prefix/len" strings; the configured route stands. Empty normally. |
serviceId |
string(uuid) | null | The stable subject id AAA resolved for this subscriber (the accounting partition key), or null when the auth driver supplied none. |
serviceState |
string | What the data plane enforces for the session: `Active`, `Restricted` (walled garden only) or `Blocked` (all subscriber traffic dropped). |
sessionTimeoutSeconds |
RADIUS Session-Timeout being enforced; 0 = none. | |
subscriberKey |
string | The subscriber's durable identity — what the throughput history is kept under, and the same across reconnects. A type prefix and a value, the first that applies: `svc:` the AAA service id, `user:` the username (lower-cased), `cid:` the DHCP Option-82 circuit-id (hex), `port:` port:S-VLAN:VLAN. |
subscriberReference |
string | null | The reference of the line the session belongs to, as people know it (e.g. `FTTP152238`), when the subscriber source publishes one; otherwise null. |
svlan |
Outer (service) VLAN id; 0 when untagged. | |
traffic |
||
type |
string | Session type: "ipoe" or "ppp". |
unclaimed |
boolean | True for an unclaimed (guest) session: admitted by its access NNI's default row, with no line found for its circuit yet. |
uptimeSeconds |
Seconds since the session was established. | |
username |
string | Subscriber username: the key the session is found by, always its true value. |
vlan |
Inner (customer) VLAN id; 0 when untagged. | |
vrf |
string | VRF carrying the session ("default" = global table). |
walledGarden |
boolean | True while the session is redirected to the walled garden. |
SessionDisconnectResult#
| Name | Type | Description |
|---|---|---|
id |
The disconnected session's id. | |
status |
string | Always "disconnected". |
username |
string | The disconnected subscriber's username. |
SessionL2tp#
| Name | Type | Description |
|---|---|---|
callingStationId |
string | null | The LAC's Calling Number for the call (ICRQ AVP 22) — for a wholesale broadband line, its circuit (e.g. "NMAJMN eth 0/1/49:101@FTTC6359247"); from a mobile LAC, the IMSI. Null when the LAC sent none. |
connectInfo |
string | null | The LAC's connect speeds from its ICCN, "tx/rx" in bits/s (downstream/upstream, as a FireBrick reports Connect-Info), "tx" alone when it sent no rx speed, or null when it sent neither. |
localSessionId |
Session id inside the tunnel on this appliance. | |
localTunnelId |
Tunnel id on this appliance. | |
peerIp |
string | null | Peer tunnel endpoint IP, or null when unknown. |
peerSessionId |
Session id on the peer. | |
peerTunnelId |
Tunnel id on the peer (LAC or LNS). | |
remoteHostname |
string | null | The peer's L2TP Host Name AVP, or null when unknown. |
switchedTo |
SessionL2tpLeg#
| Name | Type | Description |
|---|---|---|
localSessionId |
Session id inside the tunnel on this appliance. | |
localTunnelId |
Tunnel id on this appliance. | |
peerIp |
string | null | The far LNS's address. |
peerSessionId |
Session id on the far LNS. | |
peerTunnelId |
Tunnel id on the far LNS. |
SessionListPage#
| Name | Type | Description |
|---|---|---|
items |
Array<SessionSummary> | The page of session summaries, newest session first. |
offset |
The offset this page was taken at. | |
total |
Total sessions matching the filters (before paging). |
SessionLiveRates#
| Name | Type | Description |
|---|---|---|
intervalSeconds |
Sampling interval of the series (seconds). | |
rxBps |
Array<> | Bits/second received from the subscriber (upload). |
rxPps |
Array<> | Packets/second received from the subscriber. |
times |
Array<string(date-time)> | UTC sample timestamps; all rate arrays align to this axis. |
txBps |
Array<> | Bits/second sent to the subscriber (download). |
txPps |
Array<> | Packets/second sent to the subscriber. |
SessionRates#
| Name | Type | Description |
|---|---|---|
downKbps |
||
upKbps |
SessionSelector#
| Name | Type | Description |
|---|---|---|
acctSessionId |
string | null | The session's RADIUS Acct-Session-Id, exactly as accounting reports it (`yyyyMMddHHmmssfff-XXXXXXXX`). It names one session: an id from a session that has ended matches nothing, even when its slot is in use again. |
framedIp |
string | null | The session's assigned IPv4. |
reason |
string | null | Free text recorded on the session event and the audit log. |
sessionId |
Our session id, as the session list prints it. | |
username |
string | null | The subscriber's username — the IMSI for a SIM. |
SessionSparkline#
| Name | Type | Description |
|---|---|---|
downBps |
Array<> | 60 two-minute means of the subscriber's download rate, oldest first, ending with the last whole minute; null where there is no data. |
id |
The session id, as requested. | |
upBps |
Array<> | The same 60 points of the subscriber's upload rate; null in the same places as DownBps. |
SessionSparklines#
| Name | Type | Description |
|---|---|---|
enabled |
boolean | False when the appliance keeps no history; Items is then empty. |
items |
Array<SessionSparkline> | One entry per requested session that exists. |
stepSeconds |
Width of one point (120: two minutes, 60 points = 2 h). |
SessionsSummary#
| Name | Type | Description |
|---|---|---|
byEncap |
Session count per access encapsulation (ipoe | pppoe-local | pppoe-lac | l2tp | l2tp-lts). | |
byPort |
Array<PortSessionCount> | Session count per subscriber-facing port (LNS-terminated sessions excluded). |
byType |
Session count per session type (e.g. "ipoe", "ppp"). | |
byVrf |
Session count per VRF; sessions in the global table count under "default". | |
total |
Number of active subscriber sessions. | |
unclaimed |
Number of unclaimed (guest) sessions: circuits on an access NNI admitted by the NNI's default row, with no line yet. | |
walledGarden |
Number of sessions currently redirected to the walled garden. |
SessionSummary#
| Name | Type | Description |
|---|---|---|
bytesIn |
Bytes received from the subscriber (upload) since the session began. Only filled when the list was asked for unclaimed sessions; null otherwise. | |
bytesOut |
Bytes sent to the subscriber (download) since the session began. Only filled when the list was asked for unclaimed sessions; null otherwise. | |
displayName |
string | What to show as the subscriber: `subscriberReference` when there is one and `username` is a system-made one (`circuit:…`), otherwise `username`. |
encap |
string | Access encapsulation: ipoe | pppoe-local | pppoe-lac | l2tp (LNS-terminated) | l2tp-lts (switched onward). |
id |
BNG session id — the key for the detail/live/disconnect endpoints. | |
ipv4 |
string | null | Assigned IPv4 address, or null if the session is IPv6-only. |
ipv6 |
string | null | IPv6 WAN address, or null if not dual-stack. |
mac |
string | null | Subscriber MAC address (aa:bb:cc:dd:ee:ff), or null when unknown. |
nni |
string | null | The access NNI key the session's circuit was matched on, or null when the session was not identified by its circuit. |
plan |
string | null | Service plan name, or null when no plan is applied. |
presentedUsername |
string | null | The username the CPE itself presented, when the session runs under a different one because it was identified by its circuit; otherwise null. |
serviceState |
string | What the data plane enforces for the session: `Active`, `Restricted` (walled garden only) or `Blocked` (all subscriber traffic dropped). |
subscriberReference |
string | null | The reference of the line the session belongs to, as people know it (e.g. `FTTP152238`), when the subscriber source publishes one; otherwise null. |
svlan |
Outer (service) VLAN id; 0 when untagged. | |
type |
string | Session type: "ipoe" or "ppp". |
unclaimed |
boolean | True for an unclaimed (guest) session: its circuit is on an access NNI that accepts unknown circuits and no line has been found for it yet. It has full service and no accounting subject; the appliance re-binds it to its line once the platform has one. |
uptimeSeconds |
Seconds since the session was established. | |
username |
string | Subscriber username (PPP username, or the IPoE circuit identity). Always the true username - the key the session is found by - even when it is a synthetic one. |
vlan |
Inner (customer) VLAN id; 0 when untagged. | |
vrf |
string | VRF carrying the session ("default" = global table). |
walledGarden |
boolean | True while the session is redirected to the walled garden. |
SessionTraffic#
| Name | Type | Description |
|---|---|---|
bytesIn |
Bytes received from the subscriber. | |
bytesOut |
Bytes sent to the subscriber. | |
dropsRateLimit |
Packets dropped by the plan rate limiter. | |
dropsUrpf |
Upstream packets dropped by the uRPF source check. | |
packetsIn |
Packets received from the subscriber. | |
packetsOut |
Packets sent to the subscriber. |
SubscriberHistory#
| Name | Type | Description |
|---|---|---|
downBps |
Array<> | Mean bits/second sent to the subscriber (download) in the bucket. |
downPeakBps |
Array<> | Highest one-minute download average inside the bucket. |
enabled |
boolean | False when the appliance keeps no history (`subscriber-history enabled` is off); the series are then empty. |
range |
string | The range returned: "2h" or "24h". |
stepSeconds |
Width of one bucket: 60 for 2h, 300 for 24h. | |
subscriberKey |
string | The identity the history is kept under (see the session detail). |
times |
Array<string(date-time)> | UTC start of each bucket. |
upBps |
Array<> | Mean bits/second received from the subscriber (upload) in the bucket. |
upPeakBps |
Array<> | Highest one-minute upload average inside the bucket. |
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 |
|---|---|
| Sessions | Live subscriber sessions: list/filter, detail with traffic counters, high-resolution live rates, and force-disconnect. |