<Intro>

<EndpointHeader />

<Description>

Returns the number of messages that ended the requested period in each lifecycle status -- one row per status with activity, ordered by count descending. This is the "where did my messages end up" view (accepted, sent, delivered, undelivered, failed, rejected, expired), suitable for a status-distribution chart.
Rows are attributed to send time, not event time: a delivery confirmed during the period for a message accepted earlier counts against the earlier period, not this one. A recent period therefore under-reports `delivered` while its delivery reports are still arriving, and its counts only ever grow toward the truth. Because there are at most seven statuses, this breakdown takes no ranking, limit, or trend parameters and is never capped.
The maximum window is 365 days; requesting a longer range returns 422.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="from" type="string">

<Description>

Start date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to 30 days before `to` when omitted.

</Description>

</Parameter>

<Parameter name="to" type="string">

<Description>

End date (inclusive) in YYYY-MM-DD, interpreted as a calendar day in `timezone` (a UTC day when `timezone` is omitted). Defaults to today in that timezone when omitted. Window may not exceed 365 days.

</Description>

</Parameter>

<Parameter name="timezone" type="string">

<Description>

IANA timezone identifier (for example `Asia/Kathmandu`) to report in; defaults to UTC. Day and hour boundaries and the default window when `from` and `to` are omitted both follow it, so a calendar-day `from` or `to` names a local day. A `from` or `to` carrying its own UTC offset is rejected while this is set: pass a calendar day or a `Z` instant.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="period" type="object" required>

<Description>

The date range the response covers (echoed back from the request), plus `data_as_of`, the freshness boundary the data is current to.

</Description>

<FieldChildren kind="response">

<Field name="from" type="string" prefix="period." required>

<Description>

Inclusive start of the window the response covers -- a calendar day (YYYY-MM-DD) for day windows, or an hour boundary (RFC 3339) for hour windows.

</Description>

</Field>

<Field name="to" type="string" prefix="period." required>

<Description>

Inclusive end of the window the response covers -- a calendar day (YYYY-MM-DD) for day windows, or an hour boundary (RFC 3339) for hour windows.

</Description>

</Field>

<Field name="data_as_of" type="nullable string" prefix="period.">

<Description>

The instant the statistics in this response are current to: events recorded up to roughly this time are reflected, while more recent events may not be yet. Statistics are served from a rolling aggregation that refreshes every few seconds, so a response is near-real-time but not live; use this field to label data freshness (for example "as of 14:03") rather than assuming the numbers are to-the-second. Null when the freshness boundary is not being reported.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="data" type="array of object" required>

<Description>

Status breakdown rows, one per lifecycle status with activity, ordered by count descending. Empty when no messages had activity in the period.

</Description>

<FieldChildren kind="response">

<Field name="status" type="string" prefix="data." required>

<Description>

The lifecycle status this row counts. These are successive lifecycle stages: `accepted` was admitted for sending, `sent` was handed to the carrier, `delivered` was confirmed by the carrier, `undelivered`/`failed`/`expired` are the failure outcomes, and `rejected` was refused before a send attempt. This is the set of counted outcomes, deliberately a subset of the full message status vocabulary: the pre-send `scheduled`, the cancellation `canceled`, and the inbound-only `received` are not send outcomes and so never appear here.

</Description>

<Description>

Possible values: `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `expired`

</Description>

</Field>

<Field name="count" type="integer" prefix="data." required>

<Description>

Distinct messages that reached this lifecycle status in the period, attributed to the message's send time rather than the event's own.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="total" type="integer" required>

<Description>

Number of distinct lifecycle statuses with activity in the period (at most seven). Equal to the number of rows returned, since this breakdown is never capped.

</Description>

</Field>

</Payload>