Skip to content

Optional post-only accounting when pre-estimation is not available

POST
/v1/events

Records an accounting event without a reservation. This endpoint is optional in v0 deployments. The event MUST be applied atomically across all derived scopes before the server returns 201.
IDEMPOTENCY (NORMATIVE): - On replay with the same idempotency_key, the server MUST return the original successful response payload.
TENANCY (NORMATIVE): - subject.tenant MUST match the effective tenant derived from auth; otherwise 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

Request Body

application/json
JSON
{
  
"idempotency_key": "string",
  
"subject": "string",
  
"action": {
  
  
"kind": "string",
  
  
"name": "string",
  
  
"tags": [
  
  
  
"string"
  
  
]
  
},
  
"actual": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"overage_policy": "REJECT",
  
"metrics": {
  
  
"tokens_input": 0,
  
  
"tokens_output": 0,
  
  
"latency_ms": 0,
  
  
"model_version": "string",
  
  
"custom": {
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"client_time_ms": 0,
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Responses

Event created and atomically applied to balances

application/json
JSON
{
  
"status": "string",
  
"event_id": "string",
  
"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
Body

Samples

Powered by VitePress OpenAPI