# Get account traffic statistics

Returns total aggregated email volume and bytes across all domains owned by an account. Pass `mailboxId` to narrow the same aggregate to one mailbox — the series a mailbox overview charts. That dimension was added to the analytics write later than the rest, so a mailbox-scoped window covers traffic recorded since; `GET /domains/{domain}/events` (or `/accounts/{accountId}/events`) with the same filter remains the authoritative log.

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

### Path parameters

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

### Query parameters

- `range` ("1h" | "6h" | "24h" | "7d" | "30d", default `"24h"`) — Time window range ('1h', '6h', '24h', '7d', '30d')
- `mailboxId` (string, max 64 chars) — Narrow the aggregate to a single mailbox ULID

### Responses

**200** — Counts and bytes summed across all domains owned by this account

`application/json` → AccountTraffic

- `accountId` (string, required) — Account ID
- `byOutcome` (object, required) — Breakdown of event counts by outcome
- `domains` (string[], required) — List of domain names included in this aggregate
- `domainsTruncated` (boolean, required) — True if account owns more domains than query limit
- `estimated` (boolean, required) — True if metrics are sampled estimates
- `range` (string, required) — Time range of statistics
- `retentionDays` (integer, required) — Analytics retention window in days
- `rows` (TrafficRow[], required) — Breakdown rows grouped by outcome and route kind
  - `bytes` (integer <int64>, required) — Total message payload size in bytes in this bucket
  - `events` (integer <int64>, required) — Total number of events in this bucket
  - `outcome` (string, required) — Delivery or operation outcome (e.g. 'delivered', 'relayed', 'bounced')
  - `routeKind` (string, required) — Routing match kind ('exact', 'pattern', 'catchall', 'system')
- `totals` (object, required)
  - `bytes` (integer <int64>, required) — Total bytes across all account domains
  - `bytesIn` (integer <int64>, required) — Bytes received across all account domains over the window, by daily usage's `inboundBytes` rule (see the series point)
  - `bytesOut` (integer <int64>, required) — Bytes sent across all account domains over the window, by daily usage's `outboundBytes` rule (see the series point)
  - `events` (integer <int64>, required) — Total events across all account domains
  - `forwarded` (integer <int64>, required) — Inbound-driven egress events across all account domains — the forwarded SUBSET of outbound, counted inside it rather than beside it. The number a tenant is billed for separately, below submitted mail
- `mailboxId` (string) — Present when the aggregate was narrowed to one mailbox
- `series` (TrafficSeriesPoint[]) — Time-series buckets for charting
  - `bucket` (string, required) — Time bucket start timestamp ISO string
  - `bytes` (integer <int64>, required) — Total traffic bytes in this time bucket
  - `bytesIn` (integer <int64>, required) — Bytes received in this time bucket, by the rule daily usage counts `inboundBytes` by: each copy that reached a hosted address (stored, or filtered by its rules) and each admission to a webhook or forward route. A subset of `bytes`, sampled like it, and not deduped by delivery as the daily ledger is
  - `bytesOut` (integer <int64>, required) — Bytes sent in this time bucket, by the rule daily usage counts `outboundBytes` by: each recipient leg of a send, hosted or external, counted when the send was accepted (on the relay's success, for days before usage counted at acceptance). A forward's bytes are in neither this nor `bytesIn`, so this is not the bytes of `outbound`
  - `events` (integer <int64>, required) — Total traffic events in this time bucket
  - `forwarded` (integer <int64>, required) — The inbound-driven SUBSET of `outbound` (never a third direction): mail that left because a route was configured rather than because anyone submitted it. Bounded by the per-domain forwarding budget, billed on its own axis (forwardedMessages), and spends no send allowance
  - `inbound` (integer <int64>, required) — Messages received in this time bucket, one per copy, by the rule daily usage counts `inboundDeliveries` by: each copy that reached a hosted address (from outside, as a group member, or from a hosted sender), was filtered by its rules, or was admitted to a webhook or forward route. Deferrals, refusals, duplicates, uploads, imports and Sent copies are not counted. Sampled, and not deduped by delivery as the daily ledger is
  - `outbound` (integer <int64>, required) — Recipient legs sent in this time bucket, one per recipient, by the rule daily usage counts `outboundRecipients` by (counted when the send was accepted, or on the relay's success for days before usage counted at acceptance), plus each target a forward reached (`forwarded`). Deferrals and retries are not counted again. Sampled, and not deduped by delivery as the daily ledger is
  - `byOutcome` (object) — Breakdown of event counts keyed by outcome

**400** — validation_failed — unknown range value

`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

**502** — analytics_query_failed

`application/json` → ErrorBody

**503** — analytics_unavailable. Or 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}/traffic' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.accounts.getTraffic`](/docs/sdks/typescript/accounts/get-traffic)

```ts
const accountTraffic = await openemail.accounts.getTraffic(accountId)
```
