Alerts Operations Search
General investigation query over the security and license-expiration alerts, server-side filtered, sorted and paginated (page defaults to 0, pageSize to 20 with a maximum of 100, sorted by updatedAt DESC then alertId). Every state is returned when no state filter is given. An out-of-range page or pageSize, or an unknown state, groupMode, runtimeOutcome, sortBy or sortOrder, answers 400 (INVALID_PAGINATION, INVALID_FILTER or INVALID_SORT). For the WebSocket reconnect cursor use /api/v1/alerts. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role. Also accepts a Bearer API token with Read-only or Full access.
Zero-based page index (default 0). A negative page answers 400 INVALID_PAGINATION; it is not clamped.
Number of items per page (default 20, 1 to 100). A value outside 1 to 100 answers 400 INVALID_PAGINATION; it is not clamped.
20
Search term matching title, hostname, Alert Rule, matched protection Rule or any Rule that contributed to the alert (case-insensitive substring of the Rule name), the Security Group the alert was raised under, or the agent's current Security Group name
backup-agent
Lifecycle state filter
NEW
Filter by agent primary key
2
Filter by Alert Rule ID
1
Filter by the alert's own snapshotted enforcement mode (MONITOR, ENFORCE)
ENFORCE
Filter by the Runtime outcome shown for each alert. Display-category tokens (what the Alerts page labels each row, derived from the recorded outcome and matched rule action): OBSERVED_ONLY (Observed only: detected but not prevented, or no recorded outcome and no blocking action), BLOCKED (Blocked: PREVENTED or TERMINATED, or no recorded outcome with a Block rule in an ENFORCE Group), ALLOWED_PLAIN (Allowed: ALLOWED, or an Allow rule, but not Audit or MFA required), AUDIT (Audit: allowed by an Audit rule), MFA_REQUIRED (MFA required: allowed by an MFA-required rule). The categories partition the alerts. Raw stored-outcome tokens are still accepted and match the recorded outcome exactly: ALLOWED, DETECTED_OBSERVE, PREVENTED, TERMINATED, ERROR, CHALLENGED, CHALLENGE_FAILED. Tokens are case-insensitive; the two vocabularies share no token, and ALLOWED is the raw outcome, not the Allowed category
PREVENTED
Start timestamp filter, ISO 8601 date-time with an offset (for example 2026-01-15T09:30:00Z); any offset is accepted
2026-01-15T09:30:00Z
End timestamp filter, ISO 8601 date-time with an offset (for example 2026-01-15T09:30:00Z); any offset is accepted
2026-01-16T09:30:00Z
Sort property (default updatedAt): alertId, title, state, eventCount, createdAt or updatedAt. Any other value answers 400 INVALID_SORT.
updatedAt
Sort direction, ASC or DESC (default DESC). Any other value answers 400 INVALID_SORT.
DESC
200 OK successful response envelope. A page of the alerts that match the filters
{
"items": [
{
"alertId": 0,
"title": "string",
"description": "string",
"alertClass": "string",
"agentPk": 0,
"hostname": "string",
"groupName": "string",
"currentGroupName": "string",
"severity": 0,
"alertRuleId": 0,
"alertRuleName": "string",
"matchedRuleName": "string",
"matchedRuleAction": "string",
"matchedRuleCount": 0,
"matchedRuleNames": [
"string"
],
"mode": "string",
"outcome": "string",
"eventCount": 0,
"state": "string",
"resolutionReason": "string",
"version": 0,
"createdAt": "string",
"updatedAt": "string",
"firstSeenAt": "string",
"lastSeenAt": "string"
}
],
"page": 0,
"pageSize": 0,
"totalItems": 0,
"totalPages": 0
}
Array of items for the current page
Zero-based current page number
Number of items requested per page
Total number of items matching filter criteria
Total number of available pages
400 Bad Request: INVALID_PAGINATION when page is negative or pageSize is outside 1 to 100; INVALID_FILTER when state, groupMode or runtimeOutcome is not a known value; INVALID_SORT when sortBy is not a sortable property or sortOrder is not ASC or DESC; INVALID_ARGUMENT when since or until is not an ISO-8601 date-time or a numeric parameter is not a number
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
403 Forbidden: PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)
{
"errorCode": "string",
"message": "string",
"path": "string",
"timestamp": "string",
"reason": "string"
}
Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.
Human-readable error description
Request URI path that produced the error
Timestamp when the error occurred as an ISO 8601 date-time with offset
A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.
curl -H 'Authorization: <value>' https://{api_host}/api/v1/alerts/search