Docs

Get event by ID

GET
/events/{id}

Loads a single event by (project_id, id). Requires events.read. Events are not registered in resource_scope_index; project scope is required on the query (ADR 049). Misses and cross-project ids return 404.

Pre-claim projects return 404 (stored events stay invisible until claim).

Authorization

oauth2 events.read
headerAuthorizationBearer <token>

Scope: events.read

Path Parameters

id*string

Managed event id (evt_<opaque>).

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$

Response Body

The event was retrieved successfully.

application/json
  1. response

Wide event with event_type=auth.attempt.created.

id*string

Managed event id (evt_<opaque>).

project_id*project-id
Match^[a-zA-Z0-9_-]+$
team_id?|

Emit-time team scope, when the actor operated under a team.

event_type*string

Semantic event name (dot-separated). Discriminator for the Event union — see docs/design/api/events-catalog.md.

category*string

Wide-event category.

Value in"request""auth""session""admin""entity""signal"
occurred_at*string

When the action happened (server/storage clock, dialect-owned).

Formatdate-time
created_at*string

When the row was inserted (server/storage clock, dialect-owned).

Formatdate-time
actor_id?|

Who triggered the event.

actor_type?|

Actor kind.

entity_type?|

Resource type affected.

entity_id?|

Resource id affected.

client_id*string

Application or agent that produced the event.

token_id?string

Token id present at emit time, when any.

delegation_type?string

Delegation kind (omit when unset).

Value in"direct""delegated""pat_shared""exchanged"
delegation_id?string
grantor?string
fingerprint?string

Device fingerprint correlation id.

request_id?|

HTTP request correlation id.

session_id?|

Session correlation id.

flow_id?|

Login flow correlation id.

metadata?

Emit-time metadata, already redacted at write. Path A request.api may set client (ip, user_agent, origin) for SIEM join on request_id. Not a live risk-evaluator input.

payload*

Empty payload for event types with no typed fields (e.g. project.deleted, user.deleted, session.expired).

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 event = await client.getEvent("evt_01HZYABCDEFGHJKMNPQRSTVWXY", { project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" });
Example Response
{  "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": {}}

Was this helpful?