Cycles

Appearance

List budget ledgers​

GET
/v1/admin/budgets

Query budget ledgers by tenant, scope pattern, status, or utilization / debt / over-limit state. Returns all units for matching scopes.
AUTHORIZATION: - ApiKeyAuth: Tenant can list their own budgets only (scoped by
authenticated tenant). Filter params (over_limit, has_debt,
utilization_min, utilization_max) are supported and apply
within the authenticated tenant's budgets.

  • AdminKeyAuth: Admin operator lists budgets. tenant_id is
    OPTIONAL — when omitted, returns budgets across all tenants
    (cursor-paginated). When provided, scopes the result to that
    tenant. Filter params apply across the selected tenant scope.

FILTER SEMANTICS: - All filter params combine with AND semantics. - Filters apply BEFORE cursor pagination so cursor traversal
is stable across pages for a given filter set.

  • Budgets with allocated == 0 are treated as utilization == 0
    for the utilization_min / utilization_max bounds.
  • Servers MUST reject requests where utilization_min >
    utilization_max with HTTP 400. This is a cross-parameter
    constraint that OpenAPI cannot express in the schema, so
    it is stated here normatively.

Authorizations​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

Type
API Key (header: X-Cycles-API-Key)
or
AdminKeyAuth

Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.

Type
API Key (header: X-Admin-API-Key)

Parameters​

Query Parameters

tenant_id

When using ApiKeyAuth: ignored — the authenticated tenant from the API key is always used for scoping. When using AdminKeyAuth: OPTIONAL — when omitted, returns budgets across all tenants. When provided, scopes the result to the specified tenant.

Type
string
scope_prefix

Filter by scope prefix, e.g., "tenant:acme-corp/workspace:eng"

Type
string
unit
Type
string
Valid values
"USD_MICROCENTS""TOKENS""CREDITS""RISK_POINTS"
status
Type
string
Valid values
"ACTIVE""FROZEN""CLOSED"
over_limit

When true, returns only budgets whose overdraft_limit has been breached (is_over_limit == true on the returned ledger). When false, returns only budgets NOT over limit. Absent = no filter.

Type
boolean
has_debt

When true, returns only budgets with debt > 0. When false, returns only budgets with debt == 0. Absent = no filter.

Type
boolean
utilization_min

Inclusive lower bound on budget utilization (spent / allocated), expressed as a fraction in [0, 1]. Budgets with allocated == 0 are treated as utilization == 0. Absent = no lower bound.

Type
number
Format
"double"
Minimum
0
Maximum
1
utilization_max

Inclusive upper bound on budget utilization (spent / allocated), expressed as a fraction in [0, 1]. Budgets with allocated == 0 are treated as utilization == 0. Absent = no upper bound.

Type
number
Format
"double"
Minimum
0
Maximum
1
search

Free-text case-insensitive substring match. Matches across: tenant_id, scope. Combined with other filter params using AND semantics. Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee). Empty string MUST be treated as absent. Max length 128 characters; longer values MUST be rejected with HTTP 400.

Type
string
Max Length
128
sort_by

Sort key. When provided, results are returned in the requested order and the returned cursor encodes the sort key so "Load more" continues in sort order. utilization is computed as spent / allocated (allocated == 0 is treated as 0). commit_overage_policy is sorted by lexicographic enum order. When omitted, servers use their existing default ordering. Servers that don't recognize the parameter MUST ignore it without error (additive-parameter guarantee).

Type
string
Valid values
"tenant_id""scope""unit""status""commit_overage_policy""utilization""debt"
Default
"utilization"
sort_dir

Sort direction. Default descending.

Type
string
Valid values
"asc""desc"
Default
"desc"
cursor
Type
string
limit
Type
integer
Default
50

Responses​

Budget list

application/json
JSON
{
  
"ledgers": [
  
  
{
  
  
  
"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
}

Playground​

Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI