Skip to content

List cluster events

GET
/clusters/{cluster_id}/events
curl --request GET \
  --url 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/events?limit=20&offset=0&category=user&realm=customer-portal&order=desc' \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta'

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
cluster_id
required
string format: uuid

Query Parameters

Section titled “Query Parameters”
limit
integer
>= 1 <= 100

Maximum number of results to return.

offset
integer

Number of results to skip from the start.

start_time
string format: date-time

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

end_time
string format: date-time

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

category

Keycloak event category.

string
Allowed values: user admin

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

realm

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

string
>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9-]*$/

Example 

customer-portal

Filter by realm name.

realm_id
string format: uuid

Filter by realm UUID.

client_ids
Array<string>

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

user_id
string format: uuid

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

username
string
>= 1 characters <= 255 characters

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

types
Array<string>
Allowed values: 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

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

operation_types
Array<string>
Allowed values: CREATE UPDATE DELETE ACTION

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

error
string
>= 1 characters <= 255 characters

Filter by error code. Applies to user events only.

search
string
>= 1 characters <= 256 characters

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

order
string
Allowed values: asc desc

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

Header Parameters

Section titled “Header Parameters”
API-Version
required
string
Allowed values: 2026-06-01.beta

Responses

Section titled “Responses”

200

Section titled “200”

The request has succeeded.

Media typeapplication/json
Array<object>

A Keycloak event recorded for a cluster. Fields present depend on category: user-event fields are absent for admin events and vice versa.

object
id
required
string format: uuid
timestamp
required
string format: date-time
category
required

Keycloak event category.

string
Allowed values: user admin
realm_id
required
string
realm_name
required
string
client_id

OAuth2 client ID.

string
ip_address

Source IP address of the request.

string
geo

GeoIP data resolved from ip_address.

object
country_code
required

ISO 3166-1 alpha-2 country code.

string
country
required
string
city
required
string
latitude
required
number format: double
longitude
required
number format: double
type

User event type code. Present when category is user.

string
Allowed values: 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

Keycloak user UUID. Present when category is user.

string format: uuid
username

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.

string
session_id

OAuth2 session identifier. Present when category is user.

string
auth_method

Authentication method. Present when category is user.

string
identity_provider

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

string
grant_type

OAuth2 grant type. Present when category is user.

string
is_m2m

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

boolean
error

Error code for failed events (e.g. invalid_user_credentials). Present when category is user and the event represents a failure.

string
operation_type

Admin operation type (e.g. CREATE, UPDATE, DELETE). Present when category is admin.

string
Allowed values: CREATE UPDATE DELETE ACTION
resource_type

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

string
resource_path

Full resource path. Present when category is admin.

string
auth_user_id

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.

string format: uuid

Example 

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

Headers

Section titled “Headers”
Total-Count
required
integer

Total number of results across all pages, before pagination is applied.

Link
string

RFC 8288 Link header containing next, prev, first, and last relations.

400

Section titled “400”

The server could not understand the request due to invalid syntax.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

401

Section titled “401”

Access is unauthorized.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

403

Section titled “403”

Access is forbidden.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

Section titled “404”

The server cannot find the requested resource.

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

422

Section titled “422”

Client error

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri
errors
required
Array<object>
>= 1 items
object
field
required
string
detail
required
string
code
string
value

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "errors": [
    {
      "field": "example",
      "detail": "example",
      "code": "example",
      "value": "example"
    }
  ]
}

429

Section titled “429”

Client error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Section titled “Headers”
Retry-After
integer
RateLimit-Limit
integer
RateLimit-Remaining
integer
RateLimit-Reset
integer
X-RateLimit-Limit-Second
integer
X-RateLimit-Remaining-Second
integer
X-RateLimit-Limit-Minute
integer
X-RateLimit-Remaining-Minute
integer
X-RateLimit-Limit-Hour
integer
X-RateLimit-Remaining-Hour
integer
X-RateLimit-Limit-Day
integer
X-RateLimit-Remaining-Day
integer

500

Section titled “500”

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Section titled “501”

Server error

Media typeapplication/problem+json

RFC 9457 Problem Details object.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
required
string
instance
string format: uri

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}
© 2026 Skycloak. All Rights Reserved. Design by Yasser SolimanKeycloak™ is a trademark of the Linux Foundation. Skycloak is not affiliated with the Keycloak project.