Balances

Query current budget balances across scopes (nice-to-have)

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.

get/v1/balances

Request

  • Base URL: https://api.cycles.local
  • URL: https://api.cycles.local/v1/balances
  • Auth: API key in header X-Cycles-API-Key

Query parameters

tenantstring
workspacestring
appstring
workflowstring
agentstring
toolsetstring
include_childrenboolean
limitinteger

Maximum number of results to return

cursorstring

Opaque cursor from previous response

Response

Balance response

next_cursorstring

Opaque cursor for next page (if any).

has_moreboolean

True if next_cursor is present and more results may be available.

Example response

{
  "balances": [
    {
      "scope": "tenant:acme-corp/workspace:prod",
      "scope_path": "tenant:acme-corp/workspace:prod",
      "remaining": {
        "unit": "USD_MICROCENTS",
        "amount": 4577000
      },
      "reserved": {
        "unit": "USD_MICROCENTS",
        "amount": 500000
      },
      "spent": {
        "unit": "USD_MICROCENTS",
        "amount": 423000
      },
      "allocated": {
        "unit": "USD_MICROCENTS",
        "amount": 5500000
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.