Get inbound SMS statistics by country
GET
/v1/sms/stats/inbound/countries
const stats = await bird.sms.stats.inbound.byCountry({ from: "2026-05-01", to: "2026-05-31" });
for (const row of stats.data ?? []) {
console.log(row.country, row.received);
}stats = client.sms.stats.inbound.by_country(from_="2026-05-01", to="2026-05-31")
for row in stats.data or []:
print(row.country, row.received)stats, err := client.Sms.Stats.Inbound.ByCountry(context.Background(), bird.SmsStatsInboundByCountryParams{
From: time.Now().AddDate(0, -1, 0),
To: time.Now(),
})
if err != nil {
log.Fatal(err)
}
for _, row := range *stats.Data {
fmt.Println(*row.Country, *row.Received)
}$inboundByCountry = $bird->sms->stats->inbound->byCountry(['from' => '2026-05-01', 'to' => '2026-05-31']);
foreach ($inboundByCountry->getData() ?? [] as $row) {
echo $row->getCountry(), ' ', $row->getReceived(), PHP_EOL;
}bird sms stats inbound by-countrycurl -X GET "https://us1.platform.bird.com/v1/sms/stats/inbound/countries" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=50"Response200
{
"period": {
"from": "2026-05-01T00:00:00Z",
"to": "2026-05-25T00:00:00Z",
"data_as_of": "2026-05-25T14:03:10Z"
},
"data": [
{
"country": "US",
"received": 1840
}
],
"total": 12
}
Returns the number of messages your numbers received, grouped by the receiving number's country. Rows are ranked by volume, highest first, and use the time the carrier received each message.
Each row contains only a count because a received message has one state. The maximum window is 365 days; a longer range returns 422. Set timezone to resolve the period against your local calendar.
Query Parameters
from
string
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.
to
string
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.
timezone
string
IANA timezone identifier used to group statistics, for example Asia/Kathmandu. The default is UTC. Day and hour boundaries, including the default window when from and to are omitted, follow this timezone. When this parameter is set, pass from and to as calendar days or Z instants instead of timestamps with explicit UTC offsets.
limit
integer
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.
Response Payload
period
object
required
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.
Show child attributes
period.from
string
required
Inclusive start of the window, as a calendar day (YYYY-MM-DD) or an RFC 3339 hour boundary.
period.to
string
required
Inclusive end of the window, as a calendar day (YYYY-MM-DD) or an RFC 3339 hour boundary.
period.data_as_of
nullable string
Latest time reflected in the statistics. More recent events might not be included yet. Null when the freshness boundary is unavailable.
data
array of object
required
One row per country with activity in the period, most messages first, capped at the requested limit. A country 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.
Show child attributes
data.country
string
required
The country of the Bird number the messages arrived on, as an ISO 3166-1 alpha-2 code. This identifies where the message was received. It does not identify the sender's country.
data.received
integer
required
Distinct messages received on numbers in this country during the period.
total
integer
required
Total number of distinct countries the messages arrived in 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.