---
title: "How to query events"
description: "In this guide we will learn how to retrieve a specific set of events (e.g. VerificationEvent, IssuanceEvent) in a specific scope of the enterprise stack (e.g. in an organization or tenant). Events are enabled by…"
stack: "Enterprise Stack (commercial) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/enterprise-stack/administration/events-and-metrics/query-events
generated: 2026-07-20
---
# How to query events

In this guide we will learn how to retrieve a specific set of events (e.g. VerificationEvent, IssuanceEvent)
in a specific scope of the enterprise stack (e.g. in an organization or tenant). Events are enabled by default, meaning
as soon as you start the Enterprise Stack events start to be recorded and stored in the connected Enterprise Stack
database. At the moment, we support the events shown below.

**Supported Events**

- [**IssuanceEvent**](https://docs.walt.id/enterprise-stack/administration/events-and-metrics/event-types/issuance-event.md): This event tracks the status of credential offers that are
  initiated through
  the `credentials/issue` endpoint of the issuer service.
- [**VerificationEvent**](https://docs.walt.id/enterprise-stack/administration/events-and-metrics/event-types/verification-event.md): This event tracks the status of credential requests
  that are initiated via
  the `credentials/verify` endpoint of the verifier service.

## Query events without filters

To retrieve a set of events, we can use the `/events/query` endpoint along with an optional [filter](#crafting-the-filter) in our request. In
this example, we will not apply any [filter](#crafting-the-filter); instead, we will send an empty `{}` in the body of the request. As a result,
this will return all events that occurred within the organization specified in the query parameter.

**Note:**

We can only request events from one specific organization at a time. It is not possible to request events from two
different organizations simultaneously.

<br/>

**Option: CURL**

Endpoint: `/v1/events/query` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Events/post_v1_events_query)

  Ensure the organization is set to one your user has read access on when filtering for events.

**Example Request**

```bash
curl -X 'POST' \
  'https://{orgID}.enterprise.sandbox.walt.id/v1/events/query?organization={orgID}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

**Path Parameters**

- `orgID`: - When performing operations within an organization, it is essential to use the organization's Base URL or
  another valid host alias. For example, if your organization is named `test`, your default Base URL will
  be `test.enterprise-sandbox.walt.dev` when using the sandbox environment.

**Body**

```json
{}
```

---

**Response**

- `200` - Events retrieved successfully.

**Example Response**

```json
[
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "2a7b554a-37c7-4ae6-809f-2559bfa47913",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192586004,
    "action": {
      "type": "init_session"
    },
    "status": {
      "type": "Open"
    },
    "callId": "436a8a95-3290-4b65-94b9-a0970012d91c",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt"
  },
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "a8d78606-b297-484d-af2f-48a56b0b4732",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192721792,
    "action": {
      "type": "process_request"
    },
    "status": {
      "type": "Success"
    },
    "callId": "af341708-5722-4e04-b3c2-6b99008c7316",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt",
    "proofType": "jwt",
    "holderId": "hHAsP0_f0yRK3tKfH854d-ZG7GlApwYNpH1JFaStPuc"
  },
  {
    "type": "id.walt.commons.events.VerificationEvent",
    "eventType": "VerificationEvent",
    "_id": "e7a33f7b-024c-4ff7-980b-d47f7ed825e7",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.verifier1",
    "timestamp": 1741252466353,
    "action": {
      "type": "init_session"
    },
    "status": {
      "type": "Open"
    },
    "callId": "9c2f6b21-8d99-4a41-8950-66f5aa4485d2",
    "error": null,
    "sessionId": "bec96d15-6fe9-4553-a873-82b2ef270b15",
    "format": "vc+sd-jwt",
    "signatureAlgorithm": "",
    "credentialType": "identity_credential"
  },
  {
    "type": "id.walt.commons.events.VerificationEvent",
    "eventType": "VerificationEvent",
    "_id": "735c7ae3-8e2b-4a5c-a257-95eec651d133",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.verifier1",
    "timestamp": 1741252709251,
    "action": {
      "type": "process_request"
    },
    "status": {
      "type": "Failure"
    },
    "callId": "c6a15ee3-b5b9-4294-a942-049b68bda0d8",
    "error": null,
    "sessionId": "bec96d15-6fe9-4553-a873-82b2ef270b15",
    "format": "vc+sd-jwt",
    "signatureAlgorithm": "",
    "credentialType": "identity_credential",
    "holderId": "DbEu8NYzFYZ8WSMapj1Y5JJCRXWdjF1r8I_UyFrBe-Q"
  }
]
```

The response we received includes two distinct events: the `IssuanceEvent` and the `VerificationEvent`. Each of these
events appears twice as they move through different stages. Initially, the status property is set to `Open`, and it
changes to either `Success` or `Failure` as the events progress.

To learn more about each event's data structure in detail, pleas go [here](https://docs.walt.id/enterprise-stack/administration/events-and-metrics/event-types/event-types-overview.md).

## Query events with filter

To retrieve a set of events, we can use the `/events/query` endpoint along with an optional [filter](#crafting-the-filter) in our request. **In
this example, we will use a [filter](#crafting-the-filter) to only see events that are coming from a specific issuer service.**

**Note:**

We can only request events from one specific organization at a time. It is not possible to request events from two
different organizations simultaneously.

<br/>

**Option: CURL**

Endpoint: `/v1/events/query` | [API Reference](https://enterprise.sandbox.walt.id/swagger/index.html#/Events/post_v1_events_query)

  Ensure the organization is set to one your user has read access on when filtering for events.

**Example Request**

```bash
curl -X 'POST' \
  'https://{orgID}.enterprise.sandbox.walt.id/v1/events/query?organization={orgID}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": [
    "waltid.mycustomer.issuer2"
  ]
}'
```

**Path Parameters**

- `orgID`: - When performing operations within an organization, it is essential to use the organization's Base URL or
  another valid host alias. For example, if your organization is named `test`, your default Base URL will
  be `test.enterprise-sandbox.walt.dev` when using the sandbox environment.

**Body**

```json
{
  "target": [
    "waltid.mycustomer.issuer2"
  ]
}
```

Here we specify that we only want to receive events that happened in a specific target. Learn more about how to 
craft your filter [here](#crafting-the-filter)

---

**Response**

- `200` - Events retrieved successfully.

**Example Response**

```json
[
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "2a7b554a-37c7-4ae6-809f-2559bfa47913",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192586004,
    "action": {
      "type": "init_session"
    },
    "status": {
      "type": "Open"
    },
    "callId": "436a8a95-3290-4b65-94b9-a0970012d91c",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt"
  },
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "a8d78606-b297-484d-af2f-48a56b0b4732",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192721792,
    "action": {
      "type": "process_request"
    },
    "status": {
      "type": "Success"
    },
    "callId": "af341708-5722-4e04-b3c2-6b99008c7316",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt",
    "proofType": "jwt",
    "holderId": "hHAsP0_f0yRK3tKfH854d-ZG7GlApwYNpH1JFaStPuc"
  }
]
```

## Crafting the Filter

When making requests to the `events/query` endpoint, you can include a filter object `{}` within the request body. This
filter allows you to specify criteria for selecting the events you are interested in.

### Filter Structure

The filter comprises **general filters** applicable to all event types and **specific filters** tailored for certain
event types. Each filter consists of a key (representing the field to be filtered) and an array of one or more values to
match against.

### General Filters

- **`eventType`**: Specifies the type of event. Possible values are `VerificationEvent` or `IssuanceEvent`.
- **`status`**: Indicates the status of the event. Possible values are `Open`, `Success`, or `Failure`.
- **`action`**: Describes the action taken. Possible values are `init_session` or `process_request`.
- **`fromTimestamp`**: A Unix timestamp in milliseconds marking the start of the time range, e.g., `1741192586004`.
- **`toTimestamp`**: A Unix timestamp in milliseconds marking the end of the time range, e.g., `1741192586004`.
- **`callId`**: A UUID representing the call, e.g., `"436a8a95-3290-4b65-94b9-a0970012d91c"`.
- **`target`**: The service or tenant where the event was triggered, e.g., `waltid.tenant1` or `waltid.tenant1.issuer1`.

### Event-Specific Filters

For specific event types, you need to include additional filters within a nested object. This nested object should be
named according to the event type: `issuanceEventFilter` for Issuance Events and `verificationEventFilter` for
Verification Events.

#### Issuance Event Filters

These filters should be included in an object called `issuanceEventFilter`:

- **`credentialConfigurationId`**: The ID of the credential configuration being issued,
  e.g., `identity_credential_vc+sd-jwt`.
- **`format`**: The format of the credential being issued, e.g., `jwt_vc_json` or `vc+sd-jwt`.
- **`sessionId`**: The OID4VC session ID.

#### Verification Event Filters

These filters should be included in an object called `verificationEventFilter`:

- **`format`**: The format of the credential being requested, e.g., `jwt_vc_json` or `vc+sd-jwt`.
- **`sessionId`**: The OID4VP session ID.
- **`signatureAlgorithm`**: The signature algorithm used.
- **`credentialType`**: The type of credential requested, e.g., `identity_credential`.
- **`holderId`**: The ID of the holder, e.g., `DbEu8NYzFYZ8WSMapj1Y5JJCRXWdjF1r8I_UyFrBe`.

### Example Queries

**Verification Event Filter Example:**

```json
{
  // GENERAL EVENT FILTERS
  "eventType": [
    "VerificationEvent"
  ],
  "status": [
    "Open",
    "Success",
    "Failure"
  ],
  "action": [
    "init_session",
    "process_request"
  ],
  // EVENT SPECIFIC FILTERS
  "verificationEventFilter": {
    "format": [
      "vc+sd-jwt",
      "jwt_vc_json"
    ]
  }
}
```

**Issuance Event Filter Example:**

```json
{
  // GENERAL EVENT FILTERS
  "eventType": [
    "IssuanceEvent"
  ],
  "status": [
    "Open",
    "Success",
    "Failure"
  ],
  "action": [
    "init_session",
    "process_request"
  ],
  // EVENT SPECIFIC FILTERS
  "issuanceEventFilter": {
    "format": [
      "vc+sd-jwt",
      "jwt_vc_json"
    ]
  }
}
```