---
title: "List cluster events"
method: GET
path: "/clusters/{cluster_id}/events"
tags: ["Cluster Events"]
---

# List cluster events

`GET /clusters/{cluster_id}/events`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/events`
- Auth: API key in header `API-Key`

Returns Keycloak user and admin events for the cluster, sorted by `timestamp` (newest first by default).

When neither `start_time` nor `end_time` is provided the query covers the last 24 hours.
The maximum date range is 90 days.

Required scope: `clusters:events:read`

## Path parameters

- `cluster_id` string, uuid, required

## Query parameters

- `limit` integer
- `offset` integer
- `start_time` string, date-time
- `end_time` string, date-time
- `category` 'user' | 'admin': Keycloak event category.
- `realm` string: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.
- `realm_id` string, uuid
- `client_ids` string[]
- `user_id` string, uuid
- `username` string
- `types` UserEventType[]
- `operation_types` AdminOperationType[]
- `error` string
- `search` string
- `order` 'asc' | 'desc': Sort direction.

## Headers

- `API-Version` '2026-06-01.beta', required

## Response `200`

The request has succeeded.

- Event[]
  - `id` string, uuid, required
  - `timestamp` string, date-time, required
  - `category` 'user' | 'admin', required: Keycloak event category.
  - `realm_id` string, required
  - `realm_name` string, required
  - `client_id` string: OAuth2 client ID.
  - `ip_address` string: Source IP address of the request.
  - `geo` EventGeoLocation: GeoIP location derived from the source IP address. Present only when GeoIP data is available.
    - `country_code` string, required: ISO 3166-1 alpha-2 country code.
    - `country` string, required
    - `city` string, required
    - `latitude` number, double, required
    - `longitude` number, double, required
  - `type` 'LOGIN' | 'LOGIN_ERROR' | 'LOGOUT' | 'REGISTER' | 'REGISTER_ERROR' | 'CODE_TO_TOKEN' | 'CODE_TO_TOKEN_ERROR' | 'REFRESH_TOKEN' | 'INTROSPECT_TOKEN' | 'CLIENT_LOGIN' | 'CLIENT_LOGIN_ERROR' | 'UPDATE_PROFILE' | 'UPDATE_EMAIL' | 'UPDATE_PASSWORD' | 'UPDATE_TOTP' | 'REMOVE_TOTP' | 'VERIFY_EMAIL' | 'SEND_RESET_PASSWORD' | 'RESET_PASSWORD' | 'FEDERATED_IDENTITY_LINK' | 'REMOVE_FEDERATED_IDENTITY' | 'IDENTITY_PROVIDER_LOGIN' | 'IDENTITY_PROVIDER_FIRST_LOGIN'
  - `user_id` string, uuid: Keycloak user UUID. Present when `category` is `user`.
  - `username` string: On a user event, the user the event is about. On an admin event, the administrator who performed the action, when the audit pipeline resolved a name for them.
  - `session_id` string: OAuth2 session identifier. Present when `category` is `user`.
  - `auth_method` string: Authentication method. Present when `category` is `user`.
  - `identity_provider` string: Federated identity provider alias, when an external login was used. Present when `category` is `user`.
  - `grant_type` string: OAuth2 grant type. Present when `category` is `user`.
  - `is_m2m` boolean: Whether this was a machine-to-machine (client credentials grant) authentication. Present when `category` is `user`.
  - `error` string: Error code for failed events (e.g. `invalid_user_credentials`). Present when `category` is `user` and the event represents a failure.
  - `operation_type` 'CREATE' | 'UPDATE' | 'DELETE' | 'ACTION'
  - `resource_type` string: Type of resource affected (e.g. `USER`, `REALM`, `CLIENT`, `GROUP`). Present when `category` is `admin`.
  - `resource_path` string: Full resource path. Present when `category` is `admin`.
  - `auth_user_id` string, uuid: Keycloak UUID of the administrator who performed the action. Present when `category` is `admin` and Keycloak recorded an authenticated actor. Distinct from `user_id`, which on a user event is the subject of the event. On an admin event the subject is identified by `resource_path` instead, so the actor needs a field of its own. A UUID. The actor's name, when the audit pipeline resolved one, is on `username`; a federated administrator has no UUID id, so `username` may be present while this is absent.

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)