Query current budget balances across scopes (nice-to-have)
GET
/v1/balances
Returns balances for scopes matching the provided subject filter. include_children MAY be ignored by v0 implementations.
SUBJECT FILTER REQUIREMENT (NORMATIVE): - At least one of tenant/workspace/app/workflow/agent/toolset MUST be provided. - If all of these filters are omitted, server MUST return 400 with error=INVALID_REQUEST.
TENANCY (NORMATIVE): - The server MUST scope results to the effective tenant derived from auth. - If the tenant query parameter is provided, it is validation-only and MUST match the effective tenant; otherwise the server MUST return 403 FORBIDDEN. - If tenant is omitted, the effective tenant is used.
Authorizations
ApiKeyAuth
Type
API Key (header: X-Cycles-API-Key)
Parameters
Query Parameters
tenant
Type
string
workspace
Type
string
app
Type
string
workflow
Type
string
agent
Type
string
toolset
Type
string
include_children
Type
boolean
Default
falselimit
Maximum number of results to return
Type
integer
Minimum
1Maximum
200Default
50cursor
Opaque cursor from previous response
Type
string
Responses
Balance response
application/json
JSON "balances": [ { "scope": "string", "scope_path": "string", "remaining": { "unit": "string", "amount": 0 }, "reserved": { "unit": "string", "amount": 0 }, "spent": { "unit": "string", "amount": 0 }, "debt": { "unit": "string", "amount": 0 }, "allocated": { "unit": "string", "amount": 0 }, "overdraft_limit": { "unit": "string", "amount": 0 }, "is_over_limit": true } ], "next_cursor": "string", "has_more": true
{
}