System Events

Get Veza platform events, including notifications and integration logs.

Operation	Syntax
List Events	GET /api/preview/events
Export Events	GET /api/preview/events/export

Event objects represent Veza platform activity, including integration parsing, notification activity, and user logins. You can list events that match a filter (such as a category or severity), or export a continuous list for integration with an external monitoring system,

For logging Veza API activity, see Audit Log API.

List events

Returns an array of Veza platform events. If a filter is specified, the endpoint only returns events matching the SCIM filter expression. This can get events with a matching category or severity, for example:

GET /api/preview/events?page_size=10&filter=category+eq+"INTEGRATIONS"+and+timestamp+ge+"2023-04-17T22:29:22.440Z"

GET/api/preview/events

Query parameters

Response

200401403404500502503

A successful response.

Body

application/json

next_page_tokenstring

eventsarray of v1CookieEventResponse (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/preview/events', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200403

{
  "next_page_token": "text",
  "events": [
    {
      "id": "text",
      "timestamp": "2024-11-18T05:46:48.722Z",
      "category": "UNKNOWN",
      "severity": "UNKNOWN",
      "name": "text",
      "message": "text",
      "entity": "UNKNOWN_ENTITY",
      "entity_id": "text",
      "error": {
        "reason": "UNKNOWN",
        "message": "text",
        "resolution": "text",
        "request_id": "text"
      },
      "entity_name": "text",
      "event_type": "text",
      "provider_id": "text"
    }
  ]
}

Export events

Returns a paginated list of platform events, intended for exporting a continuous log into an external system.

The export endpoint can return the error code ResourceExhaused. When encountered, wait for one minute before retrying the request.

GET/api/preview/events/export

Query parameters

Response

200401403404500502503

A successful response.

Body

application/json

eventsarray of v1CookieEventResponse (object)

next_page_tokenstring

Request

JavaScriptCurlPython

const response = await fetch('/api/preview/events/export', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200403

{
  "events": [
    {
      "id": "text",
      "timestamp": "2024-11-18T05:46:48.722Z",
      "category": "UNKNOWN",
      "severity": "UNKNOWN",
      "name": "text",
      "message": "text",
      "entity": "UNKNOWN_ENTITY",
      "entity_id": "text",
      "error": {
        "reason": "UNKNOWN",
        "message": "text",
        "resolution": "text",
        "request_id": "text"
      },
      "entity_name": "text",
      "event_type": "text",
      "provider_id": "text"
    }
  ],
  "next_page_token": "text"
}

To capture events when they become available without skipping any entries, first make call with a persisted_at GE "TIMESTAMP" filter:

curl -X GET "$VEZA_URL/api/preview/events/export?filter=persisted_at+GE+%222023-09-14T23:59:59.999999999Z%22&page_size=5" \
-H "authorization: Bearer $VEZA_TOKEN"

Use the next_page_token in the response to continuously call the next page:

curl -X GET "$VEZA_URL/api/preview/events/export?page_token=eyJMaXNfQ==" \
-H "authorization: Bearer $VEZA_TOKEN"

Example response:

{
  "events": [
    {
      "id": "e1560da1-bb88-4ef0-8d7f-e220fa2b33ca",
      "timestamp": "2023-09-21T12:41:27.111852371Z",
      "category": "INTEGRATIONS",
      "severity": "WARNING",
      "name": "OAA push",
      "message": "OAA data source pushed \"VEZAFILESERVER\"",
      "entity": "DATASOURCE",
      "entity_id": "b408b41f-a73b-4a73-90dc-013111d3b2d2",
      "error": {
        "reason": "OAA_PUSH_WARNINGS",
        "metadata": {
          "0": "Cannot find identity by names (values: CN=Domain Admins,CN=Users,DC=evergreentrucks,DC=local)",
          "1": "Cannot find identity by names (values: CN=Domain Users,CN=Users,DC=evergreentrucks,DC=local)",
          "2": "Empty permissions field",
          "3": "Empty identity_to_permissions field"
        },
        "message": "OAA push had warnings.",
        "resolution": "Address the warnings and push the datasource again.",
        "request_id": "be920721634911577b8223f36f06ff1e"
      },
      "entity_name": "VEZAFILESERVER",
      "event_type": "OAA push",
      "provider_id": "cbb69418-e9de-422a-945c-7e62ba3ae1ac"
    },
    {
      "id": "ee79c82d-4574-42d9-840a-7fa5c32e8c37",
      "timestamp": "2023-09-21T12:42:16.300711343Z",
      "category": "INTEGRATIONS",
      "severity": "INFO",
      "name": "Data Source extracted",
      "message": "\"VEZAFILESERVER\" Data Source extracted (0s)",
      "entity": "DATASOURCE",
      "entity_id": "b408b41f-a73b-4a73-90dc-013111d3b2d2",
      "error": null,
      "entity_name": "VEZAFILESERVER",
      "event_type": "Data Source extracted",
      "provider_id": "cbb69418-e9de-422a-945c-7e62ba3ae1ac"
    }
  ],
  "next_page_token": "eyJMaXN0SW5wdXQiOnsiQ2F0ZWdvcnkiOjAsIlNldmVyaXR5IjowLCJTdGFydFRpbWUiOiIwMDAxLTAxLTAxVDAwOjAwOjAwWiIsIkVuZFRpbWUiOiIwMDAxLTAxLTAxVDAwOjAwOjAwWiIsIkVudGl0eUlEIjoiIiwiUHJvdmlkZXJJRCI6IiIsIkV2ZW50VHlwZSI6MCwiUGVyc2lzdGVkQXRHZSI6IjIwMjMtMDktMjFUMTI6NDI6MjAuOTc4MjA0MDA5WiIsIlBhZ2luYXRpb25MYXN0SUQiOiJlZTc5YzgyZC00NTc0LTQyZDktODQwYS03ZmE1YzMyZThjMzciLCJQYWdlU2l6ZSI6NSwiT3JkZXIiOjB9fQ=="
}

Veza event schema

Field	Description	Example Value
id	Unique identifier for the event	d95ccc9c-9051-4ef7-9147-124a16409baa
timestamp	Timestamp when the event occurred	2023-05-18T14:23:35.151842912Z
category	Category of the event	SYSTEM, INTEGRATIONS, RULE, TAG, NOTIFICATION
severity	Severity level of the event	INFO, WARNING, ERROR
name	Title of the event	Tagging request failed
message	Descriptive message for the event	Tagging request failed for node test1
provider_id	Provider data source unique identifier	e88f5d72-6f79-41d1-99e3-8777e1727311
entity	Type of entity related to the event	DATASOURCE, PROVIDER, RULE, TAG, NOTIFICATION
entity_id	Unique identifier for the entity	e88f5d72-6f79-41d1-99e3-8777e1727311
entity_name	Name of entity related to the event	SYSTEM_resource_managers:500008
error	Error details	See "error object structure"
event_type	Type or category of the event	Tagging request failed

Error object structure:

• message: Error message

• metadata: Additional metadata for the failed request.

• reason: Reason for the error

• resolution: Details to prevent the error

• request_id: Unique identifier for the failed request

Event types

Veza events will have one of the following event types:

• OUTDATED_AWS_EXTRACTION_POLICY

• DATASOURCE_PARSED

• DATASOURCE_EXTRACTED

• DATASOURCE_REGISTERED

• DATASOURCE_REMOVED

• DISCOVERY_FAILED

• DISCOVERY_SUCCESS

• OAA_PUSH

• RULE_NOTIFICATION_FAILED

• TAGGING_REQUEST_FAILED

• EMAIL_NOTIFICATION

• USER_LOGIN

• USER_LOGOUT

• USER_CREATED

• USER_DELETED

• USER_EMAIL_UPDATED

• USER_ROLES_UPDATED

• USER_ENABLED

• USER_DISABLED

• USER_PASSWORD_FORCED_RESET

• API_KEY_CREATED

• API_KEY_UPDATED

• API_KEY_DELETED

• API_KEY_REVOKED

• API_KEY_REINSTATED

Event retention

Veza retains system events for one month. When requesting events outside that range, the response will have a field error message indicating the oldest valid timestamp:

{
  "field": "filter.start_time",
  "description": "Must be after or equal to 2023-05-13T21:39:21Z"
}

Pagination

Responses will contain a next_page_token when more events are available. Include this page_token in the request query to get the next batch of results.

If no page size is specified, the default is 1,000. The maximum page size is currently 10,000 records.