Query budget balances (admin-plane view)
GET
/v1/balances
Returns budget ledger balances for the authenticated tenant, with optional filtering by scope prefix and unit. This is the admin-plane balance query — the runtime-plane equivalent with subject-based filtering is defined in cycles-protocol-v0.yaml.
ADMIN-PLANE SEMANTICS: - Returns full ledger state including debt, overdraft_limit, is_over_limit - Scoped to effective tenant (derived from API key) - Supports scope_prefix filtering (prefix match on canonical scope) - Supports unit filtering
Authorizations
ApiKeyAuth
Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)
Type
API Key (header: X-Cycles-API-Key)
Parameters
Query Parameters
tenant_id
Type
string
scope_prefix
Filter by scope prefix
Type
string
unit
Type
string
Valid values
"USD_MICROCENTS""TOKENS""CREDITS""RISK_POINTS"limit
Type
integer
Default
50Minimum
1Maximum
100cursor
Type
string
Responses
Budget ledgers matching the query filters
application/json
JSON "balances": [ { "ledger_id": "string", "tenant_id": "string", "scope": "string", "scope_path": "string", "unit": "string", "allocated": { "unit": "string", "amount": 0 }, "remaining": { "unit": "string", "amount": 0 }, "reserved": { "unit": "string", "amount": 0 }, "spent": { "unit": "string", "amount": 0 }, "debt": { "unit": "string", "amount": 0 }, "overdraft_limit": { "unit": "string", "amount": 0 }, "is_over_limit": true, "commit_overage_policy": "string", "status": "string", "rollover_policy": "string", "period_start": "string", "period_end": "string", "created_at": "string", "updated_at": "string" } ], "next_cursor": "string", "has_more": true
{
}