Monitoring and reports API
The monitoring API exposes the Sign-in log (every authentication with its policy trace), accounting sessions, system events, alerts and alert rules, the dashboard summary, on-demand and scheduled reports, and data retention settings. It backs the console pages Monitor › Overview, Monitor › Sign-in log, Monitor › Connected now, Monitor › Admin login log, Monitor › Alerts and events and Monitor › Reports.
Base path and permissions
Section titled “Base path and permissions”Tenant routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. One platform route is under /api/v1/platform. Every route needs a bearer token (see API overview).
| Permission | Routes |
|---|---|
monitor:read |
Every GET below except /insight-settings. |
monitor:coa |
DELETE /session-blocks/{id} (lift a block). |
admin:read |
GET /insight-settings. |
admin:write |
Alert rule create / change / delete / test, alert acknowledge / resolve, report job create / change / delete / run, PUT /insight-settings. |
platform:admin |
GET /api/v1/platform/insight/status. |
Every change is written to the audit log (object types alert_rule, alert, report_job, insight_settings, session_block).
Conventions
Section titled “Conventions”- Times are RFC 3339 UTC in responses. The
fromandtoquery parameters accept RFC 3339,YYYY-MM-DD(UTC midnight),YYYY-MM-DDTHH:MMor Unix seconds / milliseconds.fromis inclusive,toexclusive. - Lists return
{"items": [...], "total": N, "total_capped": false}. On the high-volume lists (Sign-in log, sessions, events, alerts)totalis counted up to 10 000; above thattotalis10000andtotal_cappedistrue. Paging:limit(default 50, at most 1000) andoffset. - Text filters match exactly and case-insensitively.
*is a wildcard (username=adm*); a leading!negates (result=!ACCEPT). - MAC filters accept any notation; a partial MAC is a substring search.
- Count endpoints (
/access-tracker/counts,/events/counts,/alerts/counts) take the filters of their list and return{"total": N, "capped": false}per count.
Route summary
Section titled “Route summary”| Method | Path | Permission |
|---|---|---|
| GET | /access-tracker |
monitor:read |
| GET | /access-tracker/counts |
monitor:read |
| GET | /access-tracker/{id} |
monitor:read |
| GET | /sessions |
monitor:read |
| GET | /sessions/summary |
monitor:read |
| GET | /sessions/{id} |
monitor:read |
| GET | /session-blocks |
monitor:read |
| DELETE | /session-blocks/{id} |
monitor:coa |
| GET | /dashboard/summary |
monitor:read |
| GET | /reports |
monitor:read |
| GET | /reports/{type} |
monitor:read |
| GET | /report-jobs |
monitor:read |
| POST | /report-jobs |
admin:write |
| GET | /report-jobs/{id} |
monitor:read |
| PUT | /report-jobs/{id} |
admin:write |
| DELETE | /report-jobs/{id} |
admin:write |
| POST | /report-jobs/{id}/run |
admin:write |
| GET | /report-jobs/{id}/runs |
monitor:read |
| GET | /report-runs/{id} |
monitor:read |
| GET | /report-runs/{id}/download |
monitor:read |
| GET | /events |
monitor:read |
| GET | /events/counts |
monitor:read |
| GET | /events/{id} |
monitor:read |
| GET | /alerts |
monitor:read |
| GET | /alerts/counts |
monitor:read |
| GET | /alerts/{id} |
monitor:read |
| POST | /alerts/{id}/acknowledge |
admin:write |
| POST | /alerts/{id}/resolve |
admin:write |
| GET | /alert-rules |
monitor:read |
| POST | /alert-rules |
admin:write |
| POST | /alert-rules/test |
admin:write |
| GET | /alert-rules/{id} |
monitor:read |
| PUT | /alert-rules/{id} |
admin:write |
| DELETE | /alert-rules/{id} |
admin:write |
| GET | /insight-settings |
admin:read |
| PUT | /insight-settings |
admin:write |
| GET | /api/v1/platform/insight/status |
platform:admin |
Sign-in log
Section titled “Sign-in log”The Sign-in log records every RADIUS, TACACS+, web (captive portal) and application sign-in with its result, reason and policy trace. Credentials are never stored: password, key and similar attributes appear as "********".
GET /access-tracker
Section titled “GET /access-tracker”Permission: monitor:read
Newest first (sort=at for oldest first). List rows omit the request, computed, reply and trace documents; read /access-tracker/{id} for those.
| Query parameter | Type | Meaning |
|---|---|---|
from, to |
time | Time range. |
result |
list | ACCEPT, REJECT, DROP, ERROR, or FAILED (anything but ACCEPT). ! negates. |
protocol |
list | RADIUS, TACACS, WEBAUTH, APPLICATION. |
kind |
string | Access-Request, Accounting, TACACS-Authen, TACACS-Author, TACACS-Acct, WebLogin, AppLogin. |
username |
string | User name (* wildcard). |
mac |
string | Full MAC or fragment. |
nad |
string | Network device ID, IP address or name. |
service |
string | Access policy ID or name. |
auth_method, auth_source |
string | Authentication method / directory. |
role |
string | Records whose roles contain this role. |
posture_token |
string | HEALTHY, QUARANTINE and so on. |
error_code |
list | Comma-separated integer codes. |
command |
string | TACACS+ command substring. |
q |
string | Free text over user name, MAC, device, policy, reason, command, directory and method. |
curl -s "$AIRGATE/api/v1/t/$TENANT/access-tracker?result=FAILED&from=2026-10-29&username=alice*" \ -H "Authorization: Bearer $TOKEN"{ "items": [{ "id": "019a2f0e-6c1b-7d43-9b1e-0b5c9a8e7f10", "at": "2026-10-29T08:21:44.120Z", "protocol": "RADIUS", "kind": "Access-Request", "nad_id": "0a3c1f55-…", "nad_name": "bldg1-wlc", "nad_ip": "10.0.0.5", "username": "alice@contoso.com", "mac": "da:a1:19:3c:00:01", "service_id": "5d0d6c0e-…", "service_name": "Corp-WiFi 802.1X", "auth_method": "EAP-PEAP/EAP-MSCHAPv2", "auth_source": "Corp AD", "result": "REJECT", "error_code": 216, "reason": "User authentication failed", "roles": [], "profiles": ["[Deny Access Profile]"], "posture_token": "", "command": "", "latency_ms": 184, "node": "node-1" }], "total": 1, "total_capped": false}GET /access-tracker/counts
Section titled “GET /access-tracker/counts”Permission: monitor:read
Takes the /access-tracker filters except result.
{"all": {"total": 10422, "capped": true}, "accept": {"total": 9980, "capped": false}, "failed": {"total": 442, "capped": false}}With ?group=tacacs it returns the Admin login log counts instead: authen, authen_failed, author, author_denied, acct.
GET /access-tracker/{id}
Section titled “GET /access-tracker/{id}”Permission: monitor:read
The full record: the summary fields plus request (attributes received), computed (attributes Airgate derived), reply (attributes sent), trace (policy evaluation lines), error_text, and session (the device’s accounting session on that NAD around the request time, or null). Returns 404 when not found.
{ "id": "019a2f0e-…", "result": "ACCEPT", "error_code": 0, "error_text": "Success", "roles": ["Employee", "[User Authenticated]"], "profiles": ["Corp VLAN 10"], "request": {"User-Name": ["alice@contoso.com"], "Calling-Station-Id": ["DA-A1-19-3C-00-01"]}, "computed": {"Connection": {"NAD-IP-Address": ["10.0.0.5"], "SSID": ["Corp-WiFi"]}}, "reply": [{"name": "Tunnel-Private-Group-Id", "op": ":=", "value": "10"}], "trace": ["service Corp-WiFi 802.1X matched", "role mapping: Employee", "enforcement: Corp VLAN 10"], "session": null}Sessions
Section titled “Sessions”Session object
Section titled “Session object”{ "id": "7d1e9f04-…", "tenant_id": "…", "nad_id": "0a3c1f55-…", "nad_name": "bldg1-wlc", "nad_ip": "10.0.0.5", "acct_session_id": "5F3A2C1B-0000012A", "acct_multi_session_id": "", "username": "alice@contoso.com", "mac": "da:a1:19:3c:00:01", "framed_ip": "10.0.0.41", "nas_port": "1", "nas_port_id": "", "nas_port_type": "Wireless-802.11", "called_station_id": "00-11-22-33-44-55:Corp-WiFi", "ssid": "Corp-WiFi", "service_name": "Corp-WiFi 802.1X", "roles": ["Employee"], "profiles": ["Corp VLAN 10"], "state": "active", "started_at": "2026-10-29T08:21:45Z", "updated_at": "2026-10-29T08:36:45Z", "stopped_at": null, "session_time": 900, "input_octets": 1834502, "output_octets": 22013377, "terminate_cause": "", "attributes": {"Acct-Status-Type": ["Interim-Update"]}, "accounting": true, "authorized_at": "2026-10-29T08:21:44Z"}| Field | Meaning |
|---|---|
accounting |
false when the session is known only from the Access-Accept (the NAD has not sent accounting yet). |
terminate_cause |
The NAD’s cause, or one set by Airgate: Superseded (a new Start for the same MAC on the same NAD), Stale-Session (no update for session_stale_hours), NAS-Reboot (Accounting-On), NAS-Request (Accounting-Off). |
limits, enforcement, enforced_at, enforced_disconnect_at |
Present when the session carries session restrictions (concurrent sessions, connected time, data volume, expiry) and what Airgate did when one was exceeded. |
GET /sessions
Section titled “GET /sessions”Permission: monitor:read
| Query parameter | Type | Meaning |
|---|---|---|
state |
string | active (default), stopped or all. |
from, to |
time | Sessions overlapping the range. |
username, ssid, service |
string | * wildcard allowed. |
mac, nad, framed_ip, acct_session_id, role, q |
string | Filters. |
restriction |
string | limits (carries restrictions), enforced (a restriction acted on it) or none. |
sort |
string | -started_at (default), started_at, -updated_at, updated_at. |
GET /sessions/summary
Section titled “GET /sessions/summary”Permission: monitor:read. Same filters as /sessions.
{"sessions": 1420, "unique_users": 1180, "unique_endpoints": 1390, "input_octets": 912345678, "output_octets": 7812345678, "avg_duration_sec": 5321.5, "no_accounting": 12, "with_limits": 40, "enforced": 3, "by_ssid": [{"label": "Corp-WiFi", "count": 1100}], "active_blocks": 2}GET /sessions/{id}
Section titled “GET /sessions/{id}”Permission: monitor:read
The session plus duration_sec, access_records (up to 50 Sign-in log summaries of that device during the session, newest first) and restrictions (the live evaluation of each restriction, or null). Returns 404 when not found.
GET /session-blocks · DELETE /session-blocks/{id}
Section titled “GET /session-blocks · DELETE /session-blocks/{id}”Permission: monitor:read (GET), monitor:coa (DELETE)
Blocks created by the session restriction action “Disconnect and Block Access”. List filters: state (active, default, or all), username, mac, q, limit, offset.
{"items": [{"id": "0b7c1f3e-…", "username": "alice@contoso.com", "mac": "da:a1:19:3c:00:01", "subject": "user", "session_id": "7d1e9f04-…", "check": "session-count", "reason": "Session limit exceeded: 3 concurrent devices for alice@contoso.com (allowed 2)", "created_at": "…", "expires_at": "…", "cleared_at": null, "cleared_by": "", "active": true}], "total": 1, "total_capped": false}subject is user (the user name is blocked on any device) or endpoint (the MAC is blocked). DELETE lifts the block and keeps it as history: 204, or 404 when unknown or already lifted. Policies see blocks through the [Insight Repository] directory attribute Denylisted.
Dashboard
Section titled “Dashboard”GET /dashboard/summary
Section titled “GET /dashboard/summary”Permission: monitor:read
| Query parameter | Type | Meaning |
|---|---|---|
hours |
integer | Window, 1–168 (default 24). |
refresh |
boolean | 1 bypasses the 10-second cache. |
Returns the data of Monitor › Overview: a per-hour timeline of accepts and rejects, totals and latency, top reject reasons, top access policies, top network devices, top authentication methods, device counts by category, status and posture, session counts, guest activity, TACACS+ counts and open alerts.
{"generated_at": "2026-10-29T08:40:00Z", "window_hours": 24, "timeline": [{"hour": "2026-10-28T09:00:00Z", "accept": 412, "reject": 17, "other": 0}], "totals": {"requests": 10422, "accept": 9980, "reject": 430, "drop": 2, "error": 10, "accept_pct": 95.76, "avg_latency_ms": 38.2, "max_latency_ms": 2210}, "top_reject_reasons": [{"reason": "User not found", "error_code": 201, "count": 211}], "sessions": {"active": 1420, "active_users": 1180, "started_in_window": 6500}, "alerts": {"open": 2, "by_severity": {"WARN": 2}}}Reports
Section titled “Reports”GET /reports
Section titled “GET /reports”Permission: monitor:read. The report catalogue: {"items": [{"type", "title", "category", "description", "params"}], "total": N}.
GET /reports/{type}
Section titled “GET /reports/{type}”Permission: monitor:read
Runs a report. Range defaults to the last 24 hours, at most 400 days.
| Query parameter | Type | Meaning |
|---|---|---|
from, to |
time | Range. |
format |
string | json (default; limit default 1000, at most 10 000) or csv (streamed download; limit default and maximum 100 000). |
limit |
integer | Row limit. |
| other | The type’s filters (below). |
| Type | Content | Extra parameters |
|---|---|---|
auth-summary |
Authentication counts grouped | group_by (day, hour, service, nad, protocol, auth_method, result, reason), tz, Sign-in log filters |
failed-auths |
Failed sign-ins | Sign-in log filters |
access-tracker |
Sign-in log export | Sign-in log filters |
endpoints |
Devices seen in the range | date_field (last_seen, first_seen, profiled_at, last_auth_at), category, status, family, mac, q |
sessions |
Sessions overlapping the range | state, username, mac, nad, ssid, service, framed_ip, role, q |
guests |
Guest activity | event (e.g. login,created), username, q |
tacacs-commands |
TACACS+ commands | username, nad, result, kind, command, q |
system-events |
Events | level, category, topic, q |
alerts |
Alerts triggered in the range | status, severity, q |
curl -s -o failed.csv "$AIRGATE/api/v1/t/$TENANT/reports/failed-auths?from=2026-10-01&to=2026-11-01&format=csv" \ -H "Authorization: Bearer $TOKEN"JSON response:
{"type": "failed-auths", "title": "Failed Authentications", "from": "…", "to": "…", "generated_at": "…", "params": {"service": "Corp*"}, "columns": [{"key": "at", "label": "Time"}, {"key": "username", "label": "Username"}, {"key": "reason", "label": "Reason"}], "items": [{"at": "…", "username": "alice@contoso.com", "reason": "User authentication failed"}], "total": 1, "truncated": false, "summary": {"top_reasons": [{"label": "User authentication failed", "count": 1}]}}CSV cells that start with =, +, -, @, tab or carriage return are prefixed with ' so spreadsheets do not evaluate them. Unknown type returns 404.
Scheduled reports
Section titled “Scheduled reports”Report job object
Section titled “Report job object”{"id": "c4b3f0a2-…", "name": "Daily failures", "description": "", "report_type": "failed-auths", "params": {"service": "Corp*"}, "format": "csv", "schedule": "daily", "hour": 6, "weekday": 1, "day_of_month": 1, "timezone": "Europe/Berlin", "recipients": ["netops@contoso.com"], "enabled": true, "next_run_at": "…", "last_run_at": "…", "last_status": "success (sent to 1 recipient(s))", "created_at": "…", "updated_at": "…"}| Field | Meaning |
|---|---|
schedule |
manual, daily, weekly (weekday 0 = Sunday … 6) or monthly (day_of_month 1–28). Runs at hour:00 in timezone. |
| Period | Daily: the previous calendar day. Weekly: the 7 days before the run day. Monthly: the previous calendar month. Manual: the last 24 hours. |
params |
Only the report type’s parameters (not from / to); each value at most 1000 characters. |
recipients |
Up to 50 email addresses. Attachments over 10 MB are replaced by a download note. |
Report job routes
Section titled “Report job routes”| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /report-jobs |
monitor:read |
?q=. List envelope. |
| POST | /report-jobs |
admin:write |
name and report_type required. 201. |
| GET | /report-jobs/{id} |
monitor:read |
|
| PUT | /report-jobs/{id} |
admin:write |
Omitted fields keep their value. |
| DELETE | /report-jobs/{id} |
admin:write |
204; its runs are deleted too. |
| POST | /report-jobs/{id}/run |
admin:write |
Runs now and returns the run, 201. A failed run is stored with status: "failed". |
| GET | /report-jobs/{id}/runs |
monitor:read |
Runs, newest first. |
| GET | /report-runs/{id} |
monitor:read |
Run metadata. |
| GET | /report-runs/{id}/download |
monitor:read |
The stored CSV / JSON. 409 if the run failed. |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/report-jobs" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Daily failures", "report_type": "failed-auths", "format": "csv", "schedule": "daily", "hour": 6, "recipients": ["netops@contoso.com"]}'Run object:
{"id": "e8b1f1d4-…", "job_id": "c4b3f0a2-…", "report_type": "failed-auths", "params": {}, "format": "csv", "from": "…", "to": "…", "status": "success", "rows": 211, "truncated": false, "size_bytes": 40211, "error": "", "delivery": "sent to 1 recipient(s)", "triggered_by": "schedule", "created_at": "…"}Events
Section titled “Events”Airgate records system events such as certificate, guest, CoA, configuration-change, posture, profiling, session-restriction and alert events.
GET /events
Section titled “GET /events”Permission: monitor:read
| Query parameter | Type | Meaning |
|---|---|---|
from, to |
time | Range. |
level |
list | INFO, WARN, ERROR. |
category |
string | * wildcard. |
source |
string | Producing module. |
topic |
string | Prefix, e.g. guest.. |
q |
string | Description, topic or category substring. |
{"items": [{"id": 1842, "tenant_id": "…", "event_id": "3e0b8f8e-…", "at": "2026-10-29T08:30:12Z", "source": "coa", "level": "WARN", "category": "CoA", "topic": "coa.sent", "description": "Disconnect-Request to bldg1-wlc for da:a1:19:3c:00:01: Disconnect-NAK (Session-Context-Not-Found)", "data": {"packet": "Disconnect-Request", "nad": "bldg1-wlc", "code": "Disconnect-NAK"}}], "total": 1, "total_capped": false}GET /events/counts
Section titled “GET /events/counts”Permission: monitor:read. Counts per level with the /events filters except level: {"INFO": {"total": 812, "capped": false}, "WARN": {…}, "ERROR": {…}}.
GET /events/{id}
Section titled “GET /events/{id}”Permission: monitor:read. One event (id is an integer).
Alerts and alert rules
Section titled “Alerts and alert rules”Alert rule object
Section titled “Alert rule object”{"id": "1b4f7e2a-…", "name": "High Reject Ratio", "description": "More than half of the authentications in 5 minutes were rejected.", "type": "reject_ratio", "params": {"threshold_pct": 50, "window_minutes": 5, "min_requests": 20}, "severity": "WARN", "enabled": true, "cooldown_minutes": 60, "auto_resolve": true, "system": true, "last_evaluated_at": "…", "last_error": "", "open_alerts": 0, "created_at": "…", "updated_at": "…"}type |
Fires when | params (defaults) |
|---|---|---|
reject_ratio |
Reject percentage above threshold_pct with at least min_requests requests |
threshold_pct (50), window_minutes (5), min_requests (20), service, protocol |
reject_count |
Failed requests reach threshold |
threshold (50), window_minutes (5), service, protocol |
user_failures |
One user name fails threshold times |
threshold (10), window_minutes (10), service, protocol |
latency_p95 |
95th-percentile latency above threshold_ms |
threshold_ms (3000), window_minutes (5), min_requests (20), service, protocol |
nad_silent |
A network device that sent requests before is silent longer than minutes |
minutes (60), lookback_hours (0 = no limit), nad_ids |
watchlist |
A watched user name or MAC makes any request | usernames, macs, window_minutes (5) |
nad_problem |
A device sends RADIUS / TACACS+ with the wrong shared secret, from an unknown address, or while it may not | window_minutes (30, at least 15) |
severity is INFO, WARN (default), ERROR or CRITICAL. Rules are evaluated every minute; a firing condition opens one alert per rule and key, re-notified every cooldown_minutes (0 = never). Alerts are also published as system.alert events, which webhooks and log export can forward. Built-in rules (system: true) cannot be deleted, renamed or re-typed; disable them instead. Disabling or deleting a rule resolves its open alerts.
| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /alert-rules |
monitor:read |
?q=&type=. |
| POST | /alert-rules |
admin:write |
201; duplicate name 409. |
| POST | /alert-rules/test |
admin:write |
Evaluates an unsaved rule now: {"type", "params", "firing": [{"key", "message", "value", "details"}], "evaluated_at"}. |
| GET | /alert-rules/{id} |
monitor:read |
|
| PUT | /alert-rules/{id} |
admin:write |
Omitted fields keep their value. |
| DELETE | /alert-rules/{id} |
admin:write |
204; built-in rule 409. |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/alert-rules" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name": "Guest rejects", "type": "reject_count", "severity": "ERROR", "params": {"threshold": 100, "window_minutes": 10, "service": "Guest*"}, "cooldown_minutes": 30, "auto_resolve": true, "enabled": true}'Alert object
Section titled “Alert object”{"id": "5a0f5c6e-…", "rule_id": "1b4f7e2a-…", "rule_name": "Repeated Authentication Failures", "rule_type": "user_failures", "key": "bob", "severity": "WARN", "status": "open", "message": "User bob failed authentication 12 times in the last 10 min", "details": {"username": "bob", "failures": 12, "threshold": 10, "window_minutes": 10}, "occurrences": 3, "triggered_at": "…", "last_seen_at": "…", "notified_at": "…", "acknowledged_at": null, "acknowledged_by": "", "resolved_at": null, "resolved_by": ""}| Method | Path | Permission | Notes |
|---|---|---|---|
| GET | /alerts |
monitor:read |
Filters: status (open, acknowledged, resolved, or active = open + acknowledged), severity, rule_id, from / to, q. |
| GET | /alerts/counts |
monitor:read |
open, acknowledged, resolved, active, active_severe (active CRITICAL + ERROR). |
| GET | /alerts/{id} |
monitor:read |
|
| POST | /alerts/{id}/acknowledge |
admin:write |
200: the alert. |
| POST | /alerts/{id}/resolve |
admin:write |
200; already resolved 409. If the condition persists, a new alert opens. |
Retention settings
Section titled “Retention settings”GET /insight-settings · PUT /insight-settings
Section titled “GET /insight-settings · PUT /insight-settings”Permission: admin:read (GET), admin:write (PUT)
PUT is partial and returns the settings.
{"retention_days": 30, "event_retention_days": 90, "stats_retention_days": 395, "report_retention_days": 90, "session_stale_hours": 24, "timezone": "UTC", "updated_at": "2026-10-29T08:00:00Z"}| Field | Range | Effect |
|---|---|---|
retention_days |
1–3650 | Sign-in log records and stopped sessions older than this are deleted. |
event_retention_days |
1–3650 | Events and resolved alerts. |
stats_retention_days |
1–3650 | Hourly statistics (dashboard, auth-summary). |
report_retention_days |
1–3650 | Stored report runs. |
session_stale_hours |
0–8760 | Active sessions with no update for this long are closed (Stale-Session); 0 disables. |
timezone |
IANA zone | Default for report buckets, schedules and daily counters. |
Platform status
Section titled “Platform status”GET /api/v1/platform/insight/status
Section titled “GET /api/v1/platform/insight/status”Permission: platform:admin
Health of the Sign-in log writer on the answering node: queue length and capacity, records written and dropped, last flush and last error, the current storage partitions and recent platform events.
{"access_log": {"queue_len": 0, "queue_cap": 20000, "enqueued": 1203311, "written": 1203300, "dropped_queue_full": 0, "dropped_invalid": 0, "dropped_db_error": 11, "batches": 48211, "last_flush": "…", "last_error": "", "last_error_at": null}, "partitions": ["access_records_202610", "access_records_202611", "access_records_default"], "recent_events": [], "node": "node-1"}