Reservations

Get reservation details (optional, for debugging)

Retrieve current status and details of a reservation by ID. Useful for debugging and monitoring long-running operations. EXPIRY (NORMATIVE, revision 2026-07-03):

  • If the reservation exists but its status is EXPIRED, the server MUST return 410 with error=RESERVATION_EXPIRED (this operation's declared 410 response). A reservation that never existed returns 404 NOT_FOUND.
  • EXPIRED reservations remain discoverable via listReservations, which returns them as normal 200 rows with status=EXPIRED — the 410 applies only to this single-resource GET. This codifies the reference implementation's settled behavior; the pre-revision text enumerated only commit/release/extend in the 410 rule, leaving GET ambiguous.

TENANCY (NORMATIVE):

  • Under ApiKeyAuth: if the reservation exists but is owned by a different effective tenant, the server MUST return 403 FORBIDDEN.
  • Under AdminKeyAuth (added 2026-04-13): admin operators can read any reservation regardless of owning tenant; reservation_id already pins the owner so no extra parameter is needed.
get/v1/reservations/{reservation_id}

Request

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

Path parameters

reservation_idstring required

Response

Reservation details

reservation_idstring required
status'ACTIVE' | 'COMMITTED' | 'RELEASED' | 'EXPIRED' required

Reservation lifecycle state (v1+ may add additional terminal states).

idempotency_keystring
created_at_msinteger required
expires_at_msinteger required
finalized_at_msinteger

Wall-clock time at which the reservation reached a terminal state. Populated on COMMITTED and RELEASED rows only; absent on ACTIVE and EXPIRED rows. The finalized_from / finalized_to window filter on listReservations (revision 2026-05-22) operates against this same field with the same population semantics.

scope_pathstring required

Canonical scope path (server-derived)

affected_scopesstring[] required

Canonical scope identifiers impacted by this reservation, in canonical order.

metadataobject

Metadata supplied at RESERVE time (on the create-reservation request), if any. For metadata attached at COMMIT time see committed_metadata.

committed_metadataobject

Metadata supplied on the COMMIT request (CommitRequest.metadata), preserved on the reservation record. Present on COMMITTED rows whose commit carried metadata; absent otherwise. Distinct from metadata, which is captured at reserve time.

Example response

{
  "reserved": {
    "unit": "USD_MICROCENTS",
    "amount": 500000
  },
  "committed": {
    "unit": "USD_MICROCENTS",
    "amount": 500000
  }
}

Changes

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