# Get daily account usage metrics

Returns daily storage, message counts, and API request meter metrics for an account over a UTC date range.

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

### Path parameters

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

### Query parameters

- `from` (string) — First UTC day in YYYY-MM-DD format (default: 29 days ago)
- `to` (string) — Last UTC day in YYYY-MM-DD format (default: today)
- `requests` ("true" | "false") — Set to 'true' to include detailed API request count breakdown by resource and principal

### Responses

**200** — Daily usage metrics ascending by date

`application/json` → AccountUsage

- `accountId` (string, required) — Account ID
- `days` (UsageDay[], required) — Daily usage metrics for each day in range
  - `calendarObjects` (integer | null, required) — Total calendar events and tasks stored, or null
  - `closedAt` (integer | null, required) — Timestamp when the day's metrics were finalized and closed in epoch seconds, or null
  - `contactObjects` (integer | null, required) — Total address book contacts stored, or null
  - `day` (string, required) — UTC date string in YYYY-MM-DD format
  - `estimated` (boolean, required) — True if storage numbers are estimated or carried forward
  - `eventsPushedImap` (integer | null, required) — Cumulative live events pushed to IMAP IDLE clients, or null
  - `eventsPushedJmap` (integer | null, required) — Cumulative live events pushed to JMAP SSE clients, or null
  - `eventsPushedWeb` (integer | null, required) — Cumulative live events pushed to web clients, or null
  - `forwardedMessages` (integer | null, required) — Count of auto-forwarded or redirected messages, or null
  - `inboundBytes` (integer | null, required) — Total size of inbound mail in bytes, or null
  - `inboundDeliveries` (integer | null, required) — Count of messages delivered into account mailboxes, or null
  - `mailboxes` (integer | null, required) — Number of active mailboxes/identities on the account, or null
  - `mailBytes` (integer | null, required) — Total mail storage in bytes at day close (including trash), or null
  - `maxDatabaseSize` (integer | null, required) — The account's LARGEST single store's metadata database size in bytes that day (MAX across mailboxes, not a sum — the figure that measures distance to the per-store store_metadata_full ceiling), or null when not measured
  - `outboundBytes` (integer | null, required) — Total size of outbound mail relayed in bytes, or null
  - `outboundMessages` (integer | null, required) — Count of distinct outbound messages sent, or null
  - `outboundRecipients` (integer | null, required) — Total outbound recipient deliveries relayed, or null
  - `pimBytes` (integer | null, required) — Calendar and contacts storage in bytes, or null
  - `pimRelayedImap` (integer | null, required) — Retired: the mail store no longer relays pim.changed, so this is null for every day filed since. Earlier days keep the cumulative frames it relayed to imap-class sockets
  - `pimRelayedJmap` (integer | null, required) — Retired: the mail store no longer relays pim.changed, so this is null for every day filed since. Earlier days keep the cumulative frames it relayed to jmap-class sockets
  - `pimRelayedWeb` (integer | null, required) — Retired: the mail store no longer relays pim.changed, so this is null for every day filed since. Earlier days keep the cumulative frames it relayed to web-class sockets
  - `reportedAt` (integer | null, required) — Timestamp when usage was reported to billing system in epoch seconds, or null
  - `requestBytesOut` (integer | null, required) — Total API response bandwidth consumed in bytes, or null
  - `requests` (integer | null, required) — Total API requests made to this account, or null
  - `requestsRolledAt` (integer | null, required) — Timestamp when API request metrics were aggregated in epoch seconds, or null
  - `rolledAt` (integer | null, required) — Timestamp when daily usage was aggregated in epoch seconds, or null
  - `socketsAcceptedImap` (integer | null, required) — Cumulative websocket/IDLE connections opened by IMAP clients, or null
  - `socketsAcceptedJmap` (integer | null, required) — Cumulative event connections opened by JMAP clients, or null
  - `socketsAcceptedWeb` (integer | null, required) — Cumulative websocket connections opened by web clients, or null
  - `trashBytes` (integer | null, required) — Storage bytes occupied by trash messages, or null
  - `webhookDeliveries` (integer | null, required) — Count of outgoing webhook notifications, or null
- `from` (string, required) — Start date of queried usage range (YYYY-MM-DD)
- `to` (string, required) — End date of queried usage range (YYYY-MM-DD)
- `requests` (RequestBreakdownRow[]) — Summary of API calls broken down by resource and surface
  - `bytesOut` (integer <int64>, required) — Total response bytes sent for these requests
  - `count` (integer <int64>, required) — Total number of API requests matching this breakdown
  - `kind` (string, required) — Operation kind ('read', 'write', 'exempt')
  - `principal` (string, required) — Authentication principal type ('system', 'account', 'mailbox', 'none')
  - `resource` (string, required) — Resource category ('mail', 'calendar', 'contacts', 'directory', 'account', 'auth', 'other')
  - `surface` (string, required) — API interface surface ('rest', 'jmap', 'dav', 'gateway', 'webmail', 'console', 'mcp')

**400** — validation_failed (malformed or inverted range, or exceeds 400 days)

`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}/usage' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.accounts.getUsage`](/docs/sdks/typescript/accounts/get-usage)

```ts
const accountUsage = await openemail.accounts.getUsage(accountId)
```
