Alerts Operations Search

Alerts Operations Search
Search alerts with multi-attribute filtering, sorting, and pagination

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.

Request
URI
GET
https://{api_host}/api/v1/alerts/search
COPY
Query Parameters
integer
page
Optional
Constraints: minimum: 0 default: 0

Zero-based page index (default 0). A negative page answers 400 INVALID_PAGINATION; it is not clamped.

integer
pageSize
Optional
Constraints: minimum: 1 maximum: 100 default: 20

Number of items per page (default 20, 1 to 100). A value outside 1 to 100 answers 400 INVALID_PAGINATION; it is not clamped.

pageSize example
20
string
search
Optional

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

search example
backup-agent
string
state
Optional

Lifecycle state filter

state example
NEW
integer
agentPk
Optional

Filter by agent primary key

agentPk example
2
integer
alertRuleId
Optional

Filter by Alert Rule ID

alertRuleId example
1
string
groupMode
Optional

Filter by the alert's own snapshotted enforcement mode (MONITOR, ENFORCE)

groupMode example
ENFORCE
string
runtimeOutcome
Optional

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

runtimeOutcome example
PREVENTED
string
since
Optional

Start timestamp filter, ISO 8601 date-time with an offset (for example 2026-01-15T09:30:00Z); any offset is accepted

since example
2026-01-15T09:30:00Z
string
until
Optional

End timestamp filter, ISO 8601 date-time with an offset (for example 2026-01-15T09:30:00Z); any offset is accepted

until example
2026-01-16T09:30:00Z
string
sortBy
Optional
Constraints: default: updatedAt

Sort property (default updatedAt): alertId, title, state, eventCount, createdAt or updatedAt. Any other value answers 400 INVALID_SORT.

sortBy example
updatedAt
string
sortOrder
Optional
Constraints: default: DESC

Sort direction, ASC or DESC (default DESC). Any other value answers 400 INVALID_SORT.

sortOrder example
DESC

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. A page of the alerts that match the filters

Returns PaginatedResponse_AlertSummaryDto of type(s) application/json
{
    "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 object
items
Required  

Array of items for the current page

integer As int32 As int32
page
Required  
Constraints: minimum: 0

Zero-based current page number

integer As int32 As int32
pageSize
Required  
Constraints: minimum: 1 maximum: 100

Number of items requested per page

integer As int64 As int64
totalItems
Required  

Total number of items matching filter criteria

integer As int32 As int32
totalPages
Required  
Constraints: minimum: 0

Total number of available pages


400

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

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

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

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)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

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.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -H 'Authorization: <value>' https://{api_host}/api/v1/alerts/search