Reservations

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

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.

post/v1/reservations/{reservation_id}/commit

Request

  • Base URL: https://api.cycles.local
  • URL: https://api.cycles.local/v1/reservations/{reservation_id}/commit
  • Auth: API key in header X-Cycles-API-Key

Path parameters

reservation_idstring required

Headers

X-Idempotency-Keystring

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 outcome and payload (including any server-generated identifiers such as reservation_id), except that remaining_ttl_ms on a replayed createReservation or extendReservation success is a volatile response observation and is not part of the attested CyclesEvidence payload. When emitted, it MUST be recomputed from the original expires_at_ms and the current authoritative server time, never copied from the stored response; it MUST be 0 if the reservation is no longer ACTIVE. All other fields replay verbatim.

Request body

idempotency_keystring required
metadataobject

Example request

{
  "idempotency_key": "idem_20260412_run42_step1_commit",
  "actual": {
    "unit": "USD_MICROCENTS",
    "amount": 423000
  },
  "metrics": {
    "tokens_input": 1500,
    "tokens_output": 800,
    "latency_ms": 2340,
    "model_version": "claude-sonnet-4-20250514"
  }
}

Response

Commit succeeded

status'COMMITTED' required

Example response

{
  "charged": {
    "unit": "USD_MICROCENTS",
    "amount": 500000
  },
  "released": {
    "unit": "USD_MICROCENTS",
    "amount": 500000
  },
  "balances": [
    {
      "scope": "tenant:acme-corp/workspace:prod",
      "scope_path": "tenant:acme-corp/workspace:prod",
      "remaining": {
        "unit": "USD_MICROCENTS",
        "amount": 4577000
      },
      "reserved": {
        "unit": "USD_MICROCENTS",
        "amount": 500000
      },
      "spent": {
        "unit": "USD_MICROCENTS",
        "amount": 423000
      },
      "allocated": {
        "unit": "USD_MICROCENTS",
        "amount": 5500000
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.