Version 2.4.8 · latest

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.

Operations and systemAuthentication: User (some parameters admin only)4 endpoints

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.

GET/api/v2/audit/ip-switch-logsList IP switch logs

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
typestring Filter by source: manual, monitor, bandwidth, backup, backup_ip, backup_default or drain (see IpSwitchLog.type).
actionstring Filter by action: disable or enable.
node_idinteger Filter by node.
node_group_idinteger Filter by node group.
line_idinteger Filter by line.
ipstring Filter by IP (exact match).
sincestring Start time (inclusive), RFC 3339.
untilstring End time (exclusive), RFC 3339.
GET/api/v2/audit/login-logsList login logs

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring 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
ipstring Filter by source IP substring.
successboolean Only successful (true) or failed (false) logins.
methodstring Filter by login method: password (includes the TOTP step); sso (operator sign-in on behalf); admin_switch (panel admin switch).
Values ["password","sso","admin_switch"]
sincestring Start time (inclusive), RFC 3339.
untilstring End time (exclusive), RFC 3339.
GET/api/v2/audit/message-send-logsList message send logs

Authentication: Admin only

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
user_idinteger User ID
msg_idinteger Filter by message id.
user_idsstring 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_idsstring 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.
channelstring Filter by delivery channel (email, sms or webhook).
Values ["email","sms","webhook"]
webhook_idinteger Filter by webhook id (only webhook-channel records carry it).
kindstring Filter by message type or direct-send category (exact match), such as traffic-exceed.
statestring Filter by send state (done or failed).
Values ["done","failed"]
after_idinteger Only records whose id is greater than this (the panel tab badge uses it to count failures since last viewed).
GET/api/v2/audit/operation-logsList operation logs

Authentication: User (some parameters admin only)

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
tenant_idinteger Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data
tenant_idsstring 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
actionstring Filter by action prefix, such as `user.` or `config.update`.
target_typestring Filter by target type.
targetstring Fuzzy filter on the target, matching target type or target id substrings.
detailstring Fuzzy filter on the change detail JSON.
ipstring Filter by source IP substring.
sincestring Start time (inclusive), RFC 3339.
untilstring End time (exclusive), RFC 3339.

Audit logs object

FieldTypeDescription
actionstring Action: disable or enable.
Values ["disable","enable"]
actor_idinteger Actor ID.
actor_namestring Actor name (username); omitted for system tasks or when not found.
actor_typestring Actor type: user, admin, system or node.
Values ["user","admin","system","node"]
channelstring Send channel: email, sms or webhook.
Values ["email","sms","webhook"]
clientstring Login client parsed from the User-Agent as "browser · OS" (e.g. Chrome · macOS); omitted when unrecognised or for older records.
contentstring Description of the switch.
created_atstring Created at
detailobject Operation details (JSON object).
errorstring Error from the last failed attempt; empty on success.
geoGeoipLookup IP geolocation lookup result.
idinteger Record ID
ipstring IP that was switched.
kindstring Message type or direct-send category (verify_code, etc.).
line_idinteger Line ID.
methodstring Login method: password; sso (platform operator logs in on behalf with a one-time ticket); admin_switch (panel admin switches into the tenant).
Values ["password","sso","admin_switch"]
msg_idinteger Related in-app message ID; empty for direct sends.
node_group_idinteger Node group ID.
node_idinteger Node ID
reasonstring Machine-readable failure reason; empty on success.
request_idstring Request ID, for correlating with logs.
sourcestring 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.
Values ["ai"]
sso_kidstring kid of the sso key that signed the ticket for an operator login on behalf; not returned for password logins.
statestring Send state: done or failed.
Values ["done","failed"]
successboolean Whether the login succeeded.
target_deletedboolean True when the target has been deleted (a resolvable type that no longer exists).
target_idstring ID of the target object.
target_namestring 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_typestring Type of the target object.
tenant_idinteger Owner tenant (user) ID
titlestring Message title (empty for direct sends).
tostring Masked recipient; "kind/name" for the webhook channel.
triesinteger Number of send attempts.
typestring 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_atstring Updated at
read-only
user_agentstring 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_idinteger User ID
usernamestring Username
webhook_idinteger Webhook id for the webhook channel (one row per webhook when a message goes to several); empty for other channels.
webhook_namestring 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command