Events Operations List

Events Operations List
Search and list security events across the fleet with bounded time window and pagination

Searches security events by ingest time. With neither from nor to the window is the last 24 hours, with only one of them it is 24 hours on the other side of it. from must not be after to and the window must not exceed 30 days (400 INVALID_TIME_RANGE). page defaults to 0 and pageSize to 20 (1 to 100), a page that begins at row 50000 or later is refused (400 INVALID_PAGINATION), and the default sort is ingestTime DESC. severity filters one value, while severityMin and severityMax filter a range (severity supplies whichever bound is not given). agentId is the external agent identifier and agentPk the internal agent primary key, and when both are given both must match. An unknown eventClass, eventCategory, outcome, operation, sortBy or sortOrder, or a q shorter than 3 or longer than 100 characters after trimming, answers 400 INVALID_ARGUMENT. Requires the ADMIN, SECURITY_OPERATOR or AUDITOR role.

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

Zero-based page index (default 0). A negative page, or a page that begins at row 50000 or later (page times pageSize), 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. Only the first 50000 rows of the result can be paged.

pageSize example
20
string
from
Optional

Start timestamp, ISO 8601 date-time with an offset (for example 2026-01-15T09:30:00Z); any offset is accepted. Defaults to 24 hours prior if omitted.

from example
2026-01-15T09:30:00Z
string
to
Optional

End timestamp, ISO 8601 date-time with an offset (for example 2026-01-15T09:30:00Z); any offset is accepted. Defaults to current timestamp if omitted.

to example
2026-01-16T09:30:00Z
string
agentId
Optional

Filter by external agent identifier (string-serialized 64-bit integer)

agentId example
2
integer
agentPk
Optional
Constraints: minimum: 1

Filter by internal agent primary key (the agentPk carried by alerts); additive to agentId, a positive int64. When both are supplied both must match.

agentPk example
2
integer
groupId
Optional

Filter by security group ID

groupId example
1
eventClass
Optional

Filter by architectural event class

eventClass example
EXEC
eventCategory
Optional

Filter by operational subcategory

eventCategory example
NETWORK
outcome
Optional

Filter by event outcome

outcome example
ALLOWED
integer
severityMin
Optional
Constraints: minimum: 1 maximum: 100

Filter by minimum severity (1-100)

severityMin example
50
integer
severityMax
Optional
Constraints: minimum: 1 maximum: 100

Filter by maximum severity (1-100)

severityMax example
100
integer
ruleId
Optional

Filter by matched rule ID

ruleId example
7
boolean
isAlert
Optional

Reserved, because events are never marked as alert events, so true returns nothing and false returns every event. The Events page does not use it

isAlert example
true
operation
Optional

Filter by the Agent operation stored in syscallOrAction, for example RULE_OP_SSH_MFA to isolate SSH MFA events. An unknown value answers 400 INVALID_ARGUMENT.

operation example
RULE_OP_SSH_MFA
string
q
Optional
Constraints: minLength: 3 maxLength: 100

Free-text search, a case-insensitive substring over description, resolvedPath, syscallOrAction, argv, the matched rule name, the rule GUID, the Hypervisor hostname and the Group name, ANDed with every other filter and the time window. 3 to 100 characters after trimming, otherwise 400 INVALID_ARGUMENT. The characters % _ and backslash are literal.

q example
invalid totp
sortBy
Optional
Constraints: default: ingestTime

Sort field (default ingestTime): ingestTime, eventTime, severity, eventClass or outcome. Any other value answers 400 INVALID_ARGUMENT.

sortBy example
ingestTime
sortOrder
Optional
Constraints: default: DESC

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

sortOrder example
ASC

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. A page of event summaries inside the ingest-time window

Returns PaginatedResponse_EventSummaryDto of type(s) application/json
{
    "items": [
        {
            "id": "00000000-0000-4000-8000-000000000062",
            "ingestTime": "2026-01-15T09:20:01Z",
            "eventTime": "2026-01-15T09:20:00Z",
            "agentId": "2",
            "hostname": "esx02.example.com",
            "securityGroupId": 1,
            "securityGroupName": "Production Servers",
            "eventClass": "EXEC",
            "eventCategory": "PROCESS_EXECUTION",
            "syscallOrAction": "execve",
            "resolvedPath": "/opt/backup/backup-agent.sh",
            "outcome": "PREVENTED",
            "severity": 80,
            "description": "Execution of /opt/backup/backup-agent.sh blocked",
            "enforcementMode": "ENFORCE",
            "matchedRuleId": 12,
            "matchedRuleName": "Block Unapproved Scripts",
            "isAlert": true,
            "binaryHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
            "policyVersion": 3
        },
        {
            "id": "00000000-0000-4000-8000-000000000061",
            "ingestTime": "2026-01-15T09:12:01Z",
            "eventTime": "2026-01-15T09:12:00Z",
            "agentId": "2",
            "hostname": "esx02.example.com",
            "securityGroupId": 1,
            "securityGroupName": "Production Servers",
            "eventClass": "NET",
            "eventCategory": "NETWORK",
            "syscallOrAction": "Connect",
            "resolvedPath": null,
            "outcome": "PREVENTED",
            "severity": 70,
            "description": "Outbound connection to 203.0.113.50:443 blocked",
            "enforcementMode": "ENFORCE",
            "matchedRuleId": null,
            "matchedRuleName": null,
            "isAlert": false,
            "binaryHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
            "policyVersion": 3
        }
    ],
    "page": 0,
    "pageSize": 20,
    "totalItems": 2,
    "totalPages": 1,
    "totalCapped": false
}
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  
Constraints: maximum: 50000

Total number of items matching filter criteria (bounded to 50000; see totalCapped)

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

Total number of available pages

boolean
totalCapped
Required  

True when more matches exist than the 50000-row count cap, so totalItems is a lower bound


400

400 Bad Request: INVALID_TIME_RANGE when from is after to or the window is longer than 30 days; INVALID_PAGINATION when page is negative or pageSize is out of range; INVALID_ARGUMENT when a filter or sort value is unknown or out of range, an id filter is not a positive number, or a parameter has the wrong type

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.


500

500 Internal Server Error: INTERNAL_ERROR when the server fails unexpectedly; the message carries no detail

Returns InternalError 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/events