---
description: Get Veza platform events, including notifications and integration logs.
---

# System Events

| Operation                       | Syntax                         |
| ------------------------------- | ------------------------------ |
| [List Events](#list-events)     | GET /api/preview/events        |
| [Export 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](audit-logs).

#### 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"`

{% openapi src="https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-2565420c2dd39112bc89df7f5b2e1522412da496%2Fopenapi.yaml?alt=media" path="/api/preview/events" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-2565420c2dd39112bc89df7f5b2e1522412da496%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### 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.

{% openapi src="https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-2565420c2dd39112bc89df7f5b2e1522412da496%2Fopenapi.yaml?alt=media" path="/api/preview/events/export" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-2565420c2dd39112bc89df7f5b2e1522412da496%2Fopenapi.yaml?alt=media)
{% endopenapi %}

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

```shell
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:

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

Example response:

```json
{
  "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:

```json
{
  "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.
