Audit logs audit
Read-only login, operation, node IP switch and message delivery logs, filterable by user, time and more.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/audit/ip-switch-logsList IP switch logs
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
type | string | Filter by source: manual, monitor, bandwidth, backup, backup_ip, backup_default or drain (see IpSwitchLog.type). |
action | string | Filter by action: disable or enable. |
node_id | integer | Filter by node. |
node_group_id | integer | Filter by node group. |
line_id | integer | Filter by line. |
ip | string | Filter by IP (exact match). |
since | string | Start time (inclusive), RFC 3339. |
until | string | End time (exclusive), RFC 3339. |
/api/v2/audit/login-logsList login logs
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
ip | string | Filter by source IP substring. |
success | boolean | Only successful (true) or failed (false) logins. |
method | string | Filter by login method: password (includes the TOTP step); sso (operator sign-in on behalf); admin_switch (panel admin switch). |
since | string | Start time (inclusive), RFC 3339. |
until | string | End time (exclusive), RFC 3339. |
/api/v2/audit/message-send-logsList message send logs
Authentication: Admin only
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
user_id | integer | User ID |
msg_id | integer | Filter by message id. |
user_ids | string | Only these users: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); combined with user_id as an intersection. |
msg_ids | string | Only these messages: comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); combined with msg_id as an intersection. |
channel | string | Filter by delivery channel (email, sms or webhook). |
webhook_id | integer | Filter by webhook id (only webhook-channel records carry it). |
kind | string | Filter by message type or direct-send category (exact match), such as traffic-exceed. |
state | string | Filter by send state (done or failed). |
after_id | integer | Only records whose id is greater than this (the panel tab badge uses it to count failures since last viewed). |
/api/v2/audit/operation-logsList operation logs
Authentication: User (some parameters admin only)
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
tenant_id | integer | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
tenant_ids | string | Admin only: only these tenants, comma-separated positive integers, at most 200 after deduplication (more, or a malformed value, returns 422); a single ID works too. Filters only and does not switch the request scope; combined with tenant_id and other filters as an intersection. A tenant credential sending a non-empty value gets 403 |
action | string | Filter by action prefix, such as `user.` or `config.update`. |
target_type | string | Filter by target type. |
target | string | Fuzzy filter on the target, matching target type or target id substrings. |
detail | string | Fuzzy filter on the change detail JSON. |
ip | string | Filter by source IP substring. |
since | string | Start time (inclusive), RFC 3339. |
until | string | End time (exclusive), RFC 3339. |
Audit logs object
| Field | Type | Description |
|---|---|---|
action | string | Action: disable or enable. |
actor_id | integer | Actor ID. |
actor_name | string | Actor name (username); omitted for system tasks or when not found. |
actor_type | string | Actor type: user, admin, system or node. |
channel | string | Send channel: email, sms or webhook. |
client | string | Login client parsed from the User-Agent as "browser · OS" (e.g. Chrome · macOS); omitted when unrecognised or for older records. |
content | string | Description of the switch. |
created_at | string | Created at |
detail | object | Operation details (JSON object). |
error | string | Error from the last failed attempt; empty on success. |
geo | GeoipLookup | IP geolocation lookup result. |
id | integer | Record ID |
ip | string | IP that was switched. |
kind | string | Message type or direct-send category (verify_code, etc.). |
line_id | integer | Line ID. |
method | string | Login method: password; sso (platform operator logs in on behalf with a one-time ticket); admin_switch (panel admin switches into the tenant). |
msg_id | integer | Related in-app message ID; empty for direct sends. |
node_group_id | integer | Node group ID. |
node_id | integer | Node ID |
reason | string | Machine-readable failure reason; empty on success. |
request_id | string | Request ID, for correlating with logs. |
source | string | How the operation was made: ai = the user ran an AI assistant plan (detail.ai carries the plan ID, operation and model); omitted for direct panel or API operations. |
sso_kid | string | kid of the sso key that signed the ticket for an operator login on behalf; not returned for password logins. |
state | string | Send state: done or failed. |
success | boolean | Whether the login succeeded. |
target_deleted | boolean | True when the target has been deleted (a resolvable type that no longer exists). |
target_id | string | ID of the target object. |
target_name | string | Target name; the snapshot taken at write time is preferred, older records are looked up by target_type and target_id; omitted when unavailable. |
target_type | string | Type of the target object. |
tenant_id | integer | Owner tenant (user) ID |
title | string | Message title (empty for direct sends). |
to | string | Masked recipient; "kind/name" for the webhook channel. |
tries | integer | Number of send attempts. |
type | string | manual: by an admin; monitor: node auto-disabled or restored by node monitoring; bandwidth: node auto-disabled when bandwidth is exceeded and restored after it falls back; backup: node group auto-switched to the backup group (enable) or back (disable); backup_ip: backup IP of a line automatically brought into DNS (enable) or taken out (disable); backup_default: default line fallback of a line automatically put into use (enable) or switched back to its own line (disable); drain: node asked to be removed from DNS before restarting nginx for an upgrade (disable) and was added back after its self-check passed or the lease expired (enable), no notification. |
updated_at | string | Updated at |
user_agent | string | Raw User-Agent of the login (already truncated when stored); omitted for older records. The panel falls back to its first token when client is empty and shows it in full on hover. |
user_id | integer | User ID |
username | string | Username |
webhook_id | integer | Webhook id for the webhook channel (one row per webhook when a message goes to several); empty for other channels. |
webhook_name | string | Current name of the webhook for the webhook channel; empty if the webhook has been deleted. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}