> Markdown version of https://authpi.com/docs/reference/core-api/events/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Events — AuthPI Core API

Audit event endpoints. Events provide a complete audit trail of all actions in your account—user signups, logins, configuration changes, and more.

## GET /v1/accounts/{account_id}/events

**List Events**

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

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor from previous response |
| `issuer_id` | string | Optional | Filter by issuer ID |
| `user_id` | string | Optional | Filter by user ID |
| `client_id` | string | Optional | Filter by client ID |
| `event_types` | string | Optional | Comma-separated list of event types (e.g., 'user.created,user.verification.succeeded') |
| `after` | number \| null | Optional | Events after this timestamp (Unix milliseconds) |
| `before` | number \| null | Optional | Events before this timestamp (Unix milliseconds) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of events | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/events/aggregate

**Aggregate Events**

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:**
```json
{
  "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).

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `issuer_id` | string | Optional | Filter by issuer ID |
| `user_id` | string | Optional | Filter by user ID |
| `client_id` | string | Optional | Filter by client ID |
| `event_types` | string | Optional | Comma-separated list of event types |
| `after` | number \| null | Optional | Events after this timestamp (Unix milliseconds) |
| `before` | number \| null | Optional | Events before this timestamp (Unix milliseconds) |
| `group_by` | type \| auth_type \| issuer_id \| user_id \| client_id \| org_id \| … | Optional | Group result rows by a single dimension |
| `interval` | hour \| day \| week | Optional | Time-bucket interval. When omitted, a single bucket spans the full window. |
| `count_unique` | string | Optional | Comma-separated distinct-count dimensions (subset of group_by values) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Aggregate result | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## GET /v1/accounts/{account_id}/events/{event_id}

**Get Event**

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.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `event_id` | string | Required | The unique identifier of the event |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Event retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |