Metrics
Inbound message counts and cost
Returns inbound messaging metrics aggregated into fixed time buckets across a window you specify, covering received message counts and inbound cost.
Requires the metrics:read scope. The plan-tier granularity gate,
10,000-bucket cap, cursor pagination via meta.next_cursor, the
meta.as_of aggregation watermark, and Cache-Control: private, max-age=30 all behave the same as on getMetricsMessages.
AuthorizationBearer <token>
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Query Parameters
metric*string
Value in
"received" | "cost_cents"from?string
Format
date-timeto?string
Format
date-timegranularity?string
Value in
"minute" | "hour" | "day"group_by?string
Value in
"channel"cursor?string
limit?integer
Default
1000Range
1 <= value <= 5000compare_to?string
Value in
"prior_period"Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/metrics/inbound?metric=received"{
"success": true,
"data": {
"metric": "messages.inbound.received",
"granularity": "hour",
"from": "2026-05-05T00:00:00Z",
"to": "2026-05-06T00:00:00Z",
"buckets": [
{
"bucket_start": "2026-05-05T00:00:00Z",
"value": 14
},
{
"bucket_start": "2026-05-05T01:00:00Z",
"value": 9
},
{
"bucket_start": "2026-05-06T00:00:00Z",
"value": null
}
]
},
"meta": {
"as_of": "2026-05-05T23:59:43Z",
"limit": 1000,
"next_cursor": null
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "GRANULARITY_NOT_AVAILABLE",
"message": "granularity not available at this plan tier",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"max_granularity": "day"
}
}
}