Get your wallet snapshot
Returns a combined wallet, subscription, and throughput-ladder snapshot for your organization, so a billing landing page can render every value it needs from a single read.
The throughput tier is read-only here. It advances automatically as your cumulative spend climbs the ladder; there is no endpoint to set it directly.
A new organization with no wallet yet renders with balance_cents: 0,
throughput_tier: 1, and the tier-1 limits. There is no error response
for an organization that has not yet topped up.
Requires the billing:read scope.
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
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/billing/wallet"{
"success": true,
"data": {
"balance_cents": 4250,
"plan_tier": "payg",
"plan_cadence": "monthly",
"subscription_status": "active",
"auto_topup_enabled": true,
"auto_topup_amount_cents": 2000,
"throughput_tier": 2,
"throughput_per_sec": 5,
"throughput_per_min": 300,
"min_topup_cents": null,
"mtd_spend_cents": 13030,
"projected_month_total_cents": 19600,
"projected_month_total_basis": "rolling_7d"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}