Public reference

Sessions

Every endpoint in this group. Open one for its parameters and a worked example.

11 Endpoints

Sessions

GET /api/v1/admin/sessions List live sessions prm_report_sessions

Sessions with no stop time, paginated with the standard list parameters. A non-admin caller sees only sessions belonging to their own manager subtree, injected server-side.

Authentication: Staff token or session
Requires permission: prm_report_sessions Sessions report

user_id is null for a session this instance cannot tie to a subscriber row, such as an anonymous voucher or an orphan left by a NAS restart. status and usage are absent on those too. Do not assume every live session has an owner.

Parameters

Parameter	Description
`q` query · string	Searches username, first and last name, framed IP, device MAC and NAS name.
`filter[nas_id]` query · integer	Sessions on one registered NAS.
`filter[kind]` query · enum	subscriber, guest, voucher or unknown.
`filter[has_ip]` query · boolean	Sessions that were assigned a framed IP.
`filter[duration_band]` query · string	Duration bucket. The value "stale" means no accounting update for longer than the tenant's idle window, which is the practical definition of a ghost session.
`filter[expired]` query · boolean	Sessions whose owner's subscription has run out but who are still connected.

Open the full reference

Response 200 OK

{
  "data": [
    {
      "id": 8821904,
      "acct_session_id": "81b0c4e2",
      "username": "ahmed",
      "user_id": 4711,
      "kind": "subscriber",
      "nas_ip": "10.20.0.1",
      "nas_id": 3,
      "nas_name": "cairo-edge-1",
      "vendor": "mikrotik",
      "framed_ip": "10.64.12.51",
      "calling_station_id": "AA:BB:CC:DD:EE:FF",
      "start_time": "2026-09-20 07:11:02",
      "update_time": "2026-09-20 09:06:02",
      "session_time": 6900,
      "input_octets": 412000000,
      "output_octets": 5100000000,
      "profile_name": "Home 20M",
      "usage": { "percent": 55.0, "dimension": "data" }
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 318, "has_next": true }
}

POST /api/v1/admin/sessions/bulk-disconnect Disconnect many sessions prm_users_live_traffic

Sends a Disconnect-Request per session id and reports the per-id outcome. One request against the write budget rather than one per session.

Authentication: Staff token or session
Requires permission: prm_users_live_traffic Live traffic / disconnect
Rate limit: t_mutate

The same NAS-accepted-it caveat as the single disconnect applies to every id in the report, and the partial-failure envelope means a 200 does not mean all of them were sent.

Parameters

Parameter	Description
`ids`required body · array	Session ids.

Open the full reference

POST /api/v1/admin/sessions/bulk-lock-mac Lock user MAC prm_users_mac_lock

Authentication: Staff token or session
Requires permission: prm_users_mac_lock Lock user MAC
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/admin/sessions/bulk-ping Ping user prm_users_ping

Authentication: Staff token or session
Requires permission: prm_users_ping Ping user
Rate limit: t_mutate

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

GET /api/v1/admin/sessions/{id} Fetch one live session prm_report_sessions

One session with the full projection, including the joined subscriber attributes.

Authentication: Staff token or session
Requires permission: prm_report_sessions Sessions report

Parameters

Parameter	Description
`id`required path · integer	The accounting row id, not the subscriber id.

Open the full reference

POST /api/v1/admin/sessions/{id}/disconnect Disconnect a session prm_users_live_traffic

Sends an RFC 5176 Disconnect-Request straight from this platform to the NAS that owns the session. The packet goes out over UDP to the device, not through the RADIUS server.

Authentication: Staff token or session
Requires permission: prm_users_live_traffic Live traffic / disconnect
Rate limit: t_mutate

ok true means the NAS ACCEPTED the packet, not that the subscriber is off the network. Whether the session actually ends is up to the device, and it will be reflected in accounting a moment later. nak true is also a success from your point of view: the NAS replied "no such session", so it is already gone. Only a 502 means the disconnect did not happen.

Parameters

Parameter	Description
`id`required path · integer	Session id.

Open the full reference

Response 200 OK

{
  "data": { "ok": true, "nak": false, "message": "disconnected" }
}

GET /api/v1/admin/sessions/{id}/live-traffic Read near-real-time throughput prm_users_live_traffic

Returns bits per second when the session's NAS has SNMP management credentials with an interface selector configured, by polling the device twice about a second apart. Without them it degrades to the accounting counters.

Authentication: Staff token or session
Requires permission: prm_users_live_traffic Live traffic / disconnect

Check the source field before trusting the numbers. source "snmp" is a real measurement; source "interim" means there were no SNMP credentials, the device was unreachable, or the sampler is not wired — the counters are the last accounting values and bps is 0, and your client has to derive the rate from successive polls itself.

Parameters

Parameter	Description
`id`required path · integer	Session id.

Open the full reference

GET /api/v1/admin/sessions/{id}/live-traffic/stream Live traffic / disconnect prm_users_live_traffic

Authentication: Staff token or session
Requires permission: prm_users_live_traffic Live traffic / disconnect

Read straight from the router that serves this instance. A hand-written description of this endpoint has not been added yet.

Open the full reference

POST /api/v1/admin/sessions/{id}/lock-mac Bind the subscriber to this session's device prm_users_mac_lock

Writes the session's calling-station MAC into the subscriber's locked-MAC list. From the next authentication onward only that device may connect. The current session is left up, since it already uses the locked MAC.

Authentication: Staff token or session
Requires permission: prm_users_mac_lock Lock user MAC
Rate limit: t_mutate

This endpoint also turns the lock ON, which the subscriber PATCH does not. Writing mac_locked_addrs through PATCH /users/{id} without setting mac_lock_enabled stores a list that enforces nothing.

Parameters

Parameter	Description
`id`required path · integer	Session id.

Open the full reference

Response 200 OK

{
  "data": {
    "user_id": 4711,
    "mac": "AA:BB:CC:DD:EE:FF",
    "locked_macs": ["AA:BB:CC:DD:EE:FF"]
  }
}

POST /api/v1/admin/sessions/{id}/ping Ping the subscriber's device prm_users_ping

Sends ICMP echo to the session's framed IP from the platform. An operator diagnostic, not a monitoring feed.

Authentication: Staff token or session
Requires permission: prm_users_ping Ping user
Rate limit: t_mutate

On the per-tenant probe budget, which is 10 a minute on a standard licence. It is sized for an operator clicking a button; a polling loop will exhaust it in six seconds and take every other probe endpoint down with it.

Parameters

Parameter	Description
`id`required path · integer	Session id.

Open the full reference

GET /api/v1/admin/sessions/{id}/traffic Poll a session's counters prm_report_sessions

The lightweight counter snapshot behind a live traffic graph. It is a snapshot, not a rate — derive throughput from the difference between two polls and the difference between their sampled_at stamps.

Authentication: Staff token or session
Requires permission: prm_report_sessions Sessions report

update_time is when the NAS last reported, and sampled_at is when this server read it. They differ by up to one accounting interval, so two polls closer together than that interval return identical counters and a throughput of zero. That is the NAS being quiet, not the subscriber.

Parameters

Parameter	Description
`id`required path · integer	Session id.

Open the full reference

Response 200 OK

{
  "data": {
    "id": 8821904,
    "session_time": 6900,
    "input_octets": 412000000,
    "output_octets": 5100000000,
    "update_time": "2026-09-20 09:06:02",
    "sampled_at": "2026-09-20 09:08:31"
  }
}

Written to be read by machines too

The reference is public and needs no account, so a tool that has never seen X-Radius can reach a correct first call on its own.

/llms.txt: An index of every page, with one-line summaries.
/llms-full.txt: The whole reference as one Markdown file, with no navigation to crawl.
/openapi.json: OpenAPI 3.1, generated from the router that serves this instance.
/skill.md: A ready-made skill file for an assistant: authentication, the response envelope and the error codes in one page.
<page-url>.md: Append .md to any reference URL for the same page as Markdown.
Accept: text/markdown: Send this header on the ordinary URL and the answer comes back as Markdown instead.

Hand this to your assistant

Read https://x-radius.com/llms.txt, then fetch the endpoint you need as Markdown by appending .md to its URL.

Try it on your own network.

50 subscribers for 7 days. You pay nothing.

Try it free Talk to us