Skip to content

Commit actual spend for a reservation (auto-releases delta)

POST
/v1/reservations/{reservation_id}/commit

Commits actual spend. If actual < reserved, delta is released automatically. If actual > reserved, behavior is controlled by the reservation's overage_policy.
IDEMPOTENCY (NORMATIVE): - On replay with the same idempotency_key, the server MUST return the original successful response payload.
TENANCY (NORMATIVE): - If the reservation exists but is owned by a different effective tenant, the server MUST return 403 FORBIDDEN.

Authorizations

ApiKeyAuth
Type
API Key (header: X-Cycles-API-Key)

Parameters

Header Parameters

X-Idempotency-Key

Optional idempotency key header. If both header and body idempotency_key are provided, they MUST match. Server MUST enforce idempotency per endpoint by (effective tenant, endpoint, idempotency_key). On replay of an idempotent request that previously succeeded, server MUST return the original successful response payload (including any server-generated identifiers such as reservation_id).

Type
string
Min Length
1
Max Length
256

Path Parameters

reservation_id*
Type
string
Required
Min Length
1
Max Length
128

Request Body

application/json
JSON
{
  
"idempotency_key": "string",
  
"actual": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"metrics": {
  
  
"tokens_input": 0,
  
  
"tokens_output": 0,
  
  
"latency_ms": 0,
  
  
"model_version": "string",
  
  
"custom": {
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Responses

Commit succeeded

application/json
JSON
{
  
"status": "string",
  
"charged": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"released": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"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
  
  
}
  
]
}

Playground

Authorization
Headers
Variables
Key
Value
Body

Samples

Powered by VitePress OpenAPI