Events — Core API

Lists audit events for an account with filtering options.

Events provide a complete audit trail of all actions in your account. Each event captures:

• What happened - Event type (user.created, session.created, client.updated, etc.)
• Who did it - User ID, client ID, or system actor
• When - Precise timestamp
• Context - IP address, user agent, request details

Common use cases:

• Security auditing and compliance
• Debugging authentication issues
• Monitoring user activity
• Alerting on suspicious patterns

Event types include:

• User events: user.created, user.updated, user.deleted
• Session events: session.created, session.terminated, session.expired, user.verification.succeeded, user.verification.failed
• Client events: client.created, client.updated, client.deleted
• Organization events: organization.created, organization.membership.created, organization.membership.deleted

Aggregates audit events into a single result or a time series, with optional grouping and distinct-count metrics. Use this when you need totals, breakdowns, or hourly sparklines without paginating through individual events.

Filters (all optional, mirror GET /events):

• issuer_id, user_id, client_id — equality filters.
• event_types — comma-separated list of event types (e.g., user.created,user.verification.succeeded).
• after, before — Unix milliseconds.

Shape parameters:

• group_by — one of type | auth_type | issuer_id | user_id | client_id | org_id | agent_id. When set, each bucket is split into one row per group key. Rows whose group key is empty/null are omitted. Use auth_type to break events down by authenticator (user, client, token, api_key, system, unauthenticated, ...).
• interval — one of hour | day | week. When set, results are bucketed by start-of-interval; when omitted, a single bucket spans the full window.
• count_unique — comma-separated subset of the same dimension list. Adds a uniques.<dim> distinct count to each row, computed over non-empty values.

Response shape:

{
  "interval": "hour",
  "group_by": "type",
  "buckets": [
    {
      "ts": 1745779200000,
      "rows": [
        { "key": "user.verification.succeeded", "count": 200, "uniques": { "user_id": 142 } }
      ]
    }
  ]
}

• ts is omitted when interval is null.
• key is omitted when group_by is null.
• uniques is omitted when count_unique is empty.
• Empty buckets are not backfilled — clients that need a fixed grid should fill gaps client-side.

Empty results:

• With no interval, an empty result still returns a single bucket with rows: [] (never an empty array). Consumers can read buckets[0].rows.length safely.
• With an interval set, an empty result returns buckets: [] (no buckets to iterate).

Retrieves the full details of a single audit event by its ID.

Use this endpoint to get complete event details including:

• Full request/response metadata
• Actor information (user, client, IP address)
• Related resource IDs
• Timestamp and duration

Event IDs are returned in list responses and webhook payloads, allowing you to fetch full details when needed.