Cycles Docs

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):

  • 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

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
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