Cycles

Appearance

List reservations (optional recovery/debug endpoint)​

GET
/v1/reservations

Lists reservations visible to the effective tenant. This endpoint is OPTIONAL in v0 deployments.

RECOVERY (NORMATIVE):

  • If a client loses reservation_id, it MAY recover it by querying with idempotency_key and/or subject filters.
  • If idempotency_key is provided, the server SHOULD return at most one matching reservation (uniqueness is expected per (effective tenant, endpoint, idempotency_key)).
  • Servers SHOULD support filtering by status=ACTIVE to identify "stuck" reservations.

SUBJECT FILTERS (GUIDANCE):

  • Query parameters tenant/workspace/app/workflow/agent/toolset filter on the canonical Subject fields.
  • Filtering on Subject.dimensions is out of scope for v0 unless explicitly implemented by the server.

TENANCY (NORMATIVE):

  • Under ApiKeyAuth: 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.
  • Under AdminKeyAuth (added 2026-04-13): the admin caller has
    no effective tenant, so the tenant query parameter is REQUIRED
    and used as a FILTER (not validation). Omitting it MUST return
    400 INVALID_REQUEST with message "tenant query parameter is
    required when using admin key authentication". This matches
    the existing dual-auth pattern on listBudgets / listPolicies
    in the governance-admin spec — same single param, semantics
    keyed on auth type.

Authorizations​

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

Parameters​

Query Parameters

idempotency_key

Lookup handle to recover the reservation_id from a prior createReservation call.

Type
string
Min Length
1
Max Length
256
status

Filter by reservation status (e.g., ACTIVE).

Type
string
Valid values
"ACTIVE""COMMITTED""RELEASED""EXPIRED"
tenant
Type
string
workspace
Type
string
app
Type
string
workflow
Type
string
agent
Type
string
toolset
Type
string
sort_by

Sort key. When provided, results are returned in the requested order and the returned cursor encodes the sort key so subsequent pages continue in sort order. When omitted, servers use their default ordering (unchanged pre-revision behavior). The reserved key sorts by the integer amount within each row; the single-unit-per- reservation invariant makes this comparison well-defined. The scope_path key sorts lexicographically over the server-derived canonical scope path string (e.g. "tenant:acme/workspace:prod/agent:x"); the tenant key sorts over the Subject.tenant field. Servers that don't recognize the parameter MUST ignore it without error.

Type
string
Valid values
"reservation_id""tenant""scope_path""status""reserved""created_at_ms""expires_at_ms"
Default
"created_at_ms"
sort_dir

Sort direction. Default descending.

Type
string
Valid values
"asc""desc"
Default
"desc"
limit

Maximum number of results to return

Type
integer
Minimum
1
Maximum
200
Default
50
cursor

Opaque cursor from previous response

Type
string

Responses​

Reservations list

application/json
JSON
{
  
"reservations": [
  
  
{
  
  
  
"reservation_id": "string",
  
  
  
"status": "string",
  
  
  
"idempotency_key": "string",
  
  
  
"subject": "string",
  
  
  
"action": {
  
  
  
  
"kind": "string",
  
  
  
  
"name": "string",
  
  
  
  
"tags": [
  
  
  
  
  
"string"
  
  
  
  
]
  
  
  
},
  
  
  
"reserved": {
  
  
  
  
"unit": "string",
  
  
  
  
"amount": 0
  
  
  
},
  
  
  
"created_at_ms": 0,
  
  
  
"expires_at_ms": 0,
  
  
  
"scope_path": "string",
  
  
  
"affected_scopes": [
  
  
  
  
"string"
  
  
  
]
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI