Wallet balance trajectory and ledger volume
Returns wallet metrics aggregated into fixed time buckets across a window you specify.
balance_end_cents is a snapshot, not a sum: it reports the wallet
balance as of the end of each bucket, carrying the prior balance
forward through buckets with no activity so dashboards get a clean
step-function plot. debit_cents and credit_cents are sums; debits
are reported as positive magnitudes.
Requires the metrics:read scope. This is the only metrics endpoint
with a default metric: it defaults to metric=balance_end_cents. 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.
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
"balance_end_cents""balance_end_cents" | "debit_cents" | "credit_cents"date-timedate-time"minute" | "hour" | "day""kind"10001 <= value <= 5000"prior_period"Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/metrics/wallet"{
"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"
}
}
}