Cluster Events

List cluster events

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

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

Path parameters

cluster_idstring uuid required

Query parameters

limitinteger

Maximum number of results to return.

offsetinteger

Number of results to skip from the start.

start_timestring date-time

Inclusive start time (ISO 8601). Defaults to 24 hours ago when omitted.

end_timestring date-time

Inclusive end time (ISO 8601). Defaults to the current time when omitted.

category'user' | 'admin'

Keycloak event category.

Filter to a specific event category. Returns both categories when omitted.

realmstring

Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

Example:customer-portal

Filter by realm name.

realm_idstring uuid

Filter by realm UUID.

client_idsstring[]

Filter by one or more OAuth2 client IDs. Accepts multiple values.

user_idstring uuid

Filter by Keycloak user UUID. Applies to user events only.

usernamestring

Filter by username prefix (case-sensitive). Applies to user events only.

typesUserEventType[]

Filter by user event type. Accepts multiple values. Applies to user events only. Mutually exclusive with operation_types.

operation_typesAdminOperationType[]

Filter by admin operation type. Accepts multiple values. Applies to admin events only. Mutually exclusive with types.

errorstring

Filter by error code. Applies to user events only.

searchstring

Case-insensitive substring search across username, client_id, realm_name, and ip_address.

order'asc' | 'desc'

Sort direction.

Sort order by timestamp. Defaults to desc (newest first).

Headers

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

Response

The request has succeeded.

idstring uuid required
timestampstring date-time required
category'user' | 'admin' required

Keycloak event category.

realm_idstring required
realm_namestring required
client_idstring

OAuth2 client ID.

ip_addressstring

Source IP address of the request.

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_idstring uuid

Keycloak user UUID. Present when category is user.

usernamestring

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_idstring

OAuth2 session identifier. Present when category is user.

auth_methodstring

Authentication method. Present when category is user.

identity_providerstring

Federated identity provider alias, when an external login was used. Present when category is user.

grant_typestring

OAuth2 grant type. Present when category is user.

is_m2mboolean

Whether this was a machine-to-machine (client credentials grant) authentication. Present when category is user.

errorstring

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_typestring

Type of resource affected (e.g. USER, REALM, CLIENT, GROUP). Present when category is admin.

resource_pathstring

Full resource path. Present when category is admin.

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

Example response

[
  {
    "geo": {
      "country_code": "US",
      "country": "United States",
      "city": "New York",
      "latitude": 40.7128,
      "longitude": -74.006
    },
    "auth_method": "openid-connect",
    "grant_type": "authorization_code",
    "error": "invalid_user_credentials",
    "resource_type": "USER",
    "resource_path": "/users/550e8400-e29b-41d4-a716-446655440000"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.