# List account audit trail

Returns a paginated list of security and directory audit events for an account. Events older than 180 days are excluded. An account keeps at most its newest 1,000,000 events: past that, the oldest are pruned as new ones are written, so a high-churn account's trail can be shorter than 180 days.

## `GET /api/v1/accounts/{accountId}/audit`

### Path parameters

- `accountId` (string, required) — Account ULID identifier

### Query parameters

- `resourceType` (string, max 64 chars) — Exact resource type, e.g. `mailbox`
- `resourceId` (string, max 255 chars) — Exact resource id — one object's history
- `action` (string, max 128 chars) — Exact action, e.g. `domain.update`
- `limit` (integer, ≥ 1, ≤ 200) — Page size (default 100)
- `cursor` (string) — Opaque page cursor from a previous response

### Responses

**200** — Page of audit events

`application/json` → object

- `events` (AuditEvent[], required)
  - `accountId` (string | null, required) — Account ID owning the touched resource, or null for system actions
  - `action` (string, required) — Action identifier (e.g. 'mailbox.delete', 'domain.update')
  - `actorId` (string, required) — Identifier of the acting API key or credential
  - `actorName` (string | null, required) — Resolved name of actor (API key name or mailbox address), or null
  - `actorType` ("system" | "account" | "mailbox" | "recipient", required) — Actor permission scope: 'system', 'account', 'mailbox', or 'recipient' — the anonymous holder of a forwarding disable link or of a verified-recipient confirmation link, identified by the capability spent rather than a credential (so `actorName` is always null for it)
  - `createdAt` (integer <int64>, required) — Action timestamp in epoch seconds
  - `detail` (object | null, required) — Sanitized JSON object describing specific property changes, or null
  - `forwardedIp` (string | null, required) — Forwarded client IP address from proxy header, or null
  - `id` (string, required) — Audit event ULID (time-ordered, newest first)
  - `ip` (string | null, required) — Direct network caller IP address, or null
  - `mailboxId` (string | null, required) — Acting mailbox ID for mailbox actors, or null
  - `resourceId` (string, required) — Target resource identifier (ULID or domain name)
  - `resourceType` (string, required) — Type of resource modified ('account', 'domain', 'mailbox', 'route', 'api_key', 'blocklist')
- `nextCursor` (string) — Opaque cursor for the next page; absent on the last page

**400** — validation_failed

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Account not found or not accessible to this principal

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/accounts/{accountId}/audit' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.accounts.listAudit`](/docs/sdks/typescript/accounts/list-audit)

```ts
for await (const auditEvent of openemail.accounts.listAudit(accountId)) {
  // every item of every page (await the call instead for one page)
}
```
