<Intro>

<EndpointHeader />

<Description>

Returns the number of messages your numbers received, broken down by operator.

Rows are ranked by volume, highest first, and counted by the time the carrier received each message. Operators are identified by MCC-MNC, which is resolved for every destination.

A row carries a count and nothing else. A received message has one state, so there is no lifecycle to break down and no delivery latency to report.

Messages whose sending operator the carrier did not report are excluded, so these rows can sum to less than the summary total for the same period.

The maximum window is 365 days; a longer range returns 422. Set `timezone` to resolve the period against your local calendar instead of UTC.

</Description>

</Intro>

<Parameters in="query">

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

<Description>

Start date (inclusive), 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), 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>

<Parameter name="limit" type="integer">

<Description>

Maximum rows to return, ranked by volume. Defaults to 50; the maximum is 200, and asking for more returns 422 rather than silently returning fewer.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

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

<Description>

The window the server actually computed against. The summary serves two window grains: calendar days (bounds are YYYY-MM-DD) and hours (bounds are RFC 3339 instants on the hour). The grain of `from` and `to` mirrors the grain of the request's bounds.

</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>

One row per operator with activity in the period, most messages first, capped at the requested `limit`. An operator with no messages in the period is absent rather than zero-filled, because unlike a time bucket it is not part of a continuous axis.

</Description>

<FieldChildren kind="response">

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

<Description>

Mobile country code and mobile network code of the network the sending subscriber is on. The breakdown keys on this rather than on an operator name because the carrier reports a name only where a surcharge applies, which would leave most of the world in one unnamed bucket.

</Description>

</Field>

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

<Description>

Distinct messages received from senders on this operator during the period.

</Description>

</Field>

</FieldChildren>

</Field>

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

<Description>

Total number of distinct sending operators with activity in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.

</Description>

</Field>

</Payload>