Docs

List events

GET
/events

Returns project-scoped audit events, newest-first by keyset on (created_at, id) (ADR 027 / ADR 049). Pass order=asc for oldest-first. Requires events.read.

Pre-claim projects return an empty list (events are stored but not visible until claim succeeds). Team-scoped credentials see only events whose emit-time team_id matches the credential team (enforced when team-scoped tokens exist).

Clients discriminate each item via event_type (OpenAPI Event oneOf) — see docs/design/api/events-catalog.md.

Authorization

oauth2 events.read
headerAuthorizationBearer <token>

Scope: events.read

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$
category?array<>

Filter by wide-event category. Repeatable (OR within the parameter).

event_type?array<string>

Exact-match filter on event_type. Repeatable (OR within the parameter).

actor_id?string
client_id?string
session_id?string
flow_id?string
request_id?string
fingerprint?string
entity_type?string
entity_id?string
team_id?string

Filter by emit-time team scope stored on the event.

created_after?string

Inclusive lower bound on created_at (RFC 3339).

Formatdate-time
created_before?string

Exclusive upper bound on created_at (RFC 3339).

Formatdate-time
order?string

Sort direction on (created_at, id). Default desc (newest first) for audit UI. Pass asc for oldest-first.

Default"desc"
Value in"asc""desc"
page_token?string

Token for fetching the next page of results. Obtain this value from next_page_token in the previous response. Omit to start from the beginning. Its format is opaque and may change between releases.

limit?integer

Maximum number of items to return.

Range1 <= value <= 100
Default20

Response Body

Events were retrieved successfully.

application/json
  1. response

Paginated list of events (ADR 027 / ADR 049).

data*array<|||||||||||||||||||||||||||||||||||||||||||>
next_page_token?|

Token to pass as page_token in the next request to fetch the following page. Absent when there are no more results.

Example Request
import { createZitadelClient } from "@zitadel/api/client";const client = createZitadelClient({  baseUrl: process.env.ZITADEL_URL ?? "http://localhost:8080",  token: process.env.ZITADEL_PROJECT_SECRET!, // server-side only});const events = await client.listEvents({ project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" });
Example Response
{  "data": [    {      "id": "string",      "project_id": "string",      "team_id": "string",      "category": "request",      "occurred_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "actor_id": "string",      "actor_type": "human",      "entity_type": "string",      "entity_id": "string",      "client_id": "string",      "token_id": "string",      "delegation_type": "direct",      "delegation_id": "string",      "grantor": "string",      "fingerprint": "string",      "request_id": "string",      "session_id": "string",      "flow_id": "string",      "metadata": {        "authorization": {          "path": "platform_operator",          "actor_home_project_id": "string"        },        "client": {          "ip": "string",          "user_agent": "string",          "origin": "string"        }      },      "event_type": "auth.attempt.created",      "payload": {}    }  ],  "next_page_token": "string"}

Was this helpful?