> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Read a reservation

> Reports a reservation's current state, what it covers, and every close already committed against it.

`closes` exists for one recovery: a client that has lost its `Idempotency-Key` and cannot reproduce the events it sent can read what already landed, instead of resending and burning twice. This is a read and cannot settle anything. An unknown or foreign token returns `404`, indistinguishably.



## OpenAPI

````yaml /api-reference/v2/specs/2026-04-01.json get /credits/reservations/{reservation_id}
openapi: 3.1.0
info:
  title: Alguna Public API
  version: '2026-04-01'
servers:
  - url: https://api.alguna.io
security:
  - bearerAuth: []
tags:
  - name: Billing Events and Metrics
  - name: Checkout Sessions
  - name: Credit Notes
  - name: Credits
  - name: Customer Portal Sessions
  - name: Customers
  - name: Insights
  - name: Integrations
  - name: Invoices
  - name: Payments
  - name: Plans
  - name: Product Bundles
  - name: Products
  - name: Refunds
  - name: Revenue Schedules
  - name: Subscription Changes
  - name: Subscription Versions
  - name: Subscriptions
  - name: Tax
  - name: Wallet Grants
  - name: Wallets
paths:
  /credits/reservations/{reservation_id}:
    get:
      tags:
        - Credits
      summary: Read a reservation
      description: >-
        Reports a reservation's current state, what it covers, and every close
        already committed against it.


        `closes` exists for one recovery: a client that has lost its
        `Idempotency-Key` and cannot reproduce the events it sent can read what
        already landed, instead of resending and burning twice. This is a read
        and cannot settle anything. An unknown or foreign token returns `404`,
        indistinguishably.
      operationId: get-credit-reservation
      parameters:
        - in: header
          name: Alguna-Version
          required: true
          schema:
            enum:
              - '2026-04-01'
            type: string
        - in: path
          name: reservation_id
          required: true
          schema:
            description: Unique identifier for the reservation
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationStatusResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
components:
  schemas:
    ReservationStatusResponse:
      properties:
        block_amount:
          description: Credits this reservation fenced when it opened.
          example: '500'
          type: string
        closes:
          description: >-
            Every close already committed, oldest first. This is how a client
            that lost its Idempotency-Key discovers what already landed instead
            of resending and burning twice.
          items:
            $ref: '#/components/schemas/ReservationCloseSummary'
          type: array
        consumed:
          description: >-
            What every close so far priced to: the sum of closes[].used, not of
            closes[].covered, less anything voided. Under on_envelope_exceeded:
            record a close can price past the hold, so this can exceed
            block_amount — and because remaining floors at zero, block_amount −
            consumed is not a way to derive it. Sum closes[].covered instead for
            what the ledger actually burned.
          example: '266'
          type: string
        expires_at:
          description: When the hold expires. Absent once terminal.
          example: '2026-04-01T10:20:00Z'
          format: date-time
          nullable: true
          type: string
        identities:
          description: >-
            The metrics this hold covers — one entry per credit-consuming metric
            its settles price against. A settle's events must carry event names
            these identities count.
          items:
            $ref: '#/components/schemas/ReservationIdentity'
          type: array
        open:
          description: Whether the reservation can still be settled against.
          type: boolean
        remaining:
          description: >-
            Credits still authorised: block_amount − consumed, floored at zero.
            Zero once the reservation is terminal, whatever the arithmetic would
            otherwise allow.
          example: '234'
          type: string
        reservation_id:
          example: crt_abc123
          type: string
        status:
          description: open, capturing, captured, released, expired, or recovery_pending.
          example: open
          type: string
      required:
        - block_amount
        - closes
        - consumed
        - identities
        - open
        - remaining
        - reservation_id
        - status
      type: object
    ErrorResponse:
      properties:
        detail:
          type: string
        status:
          format: int64
          type: integer
      required:
        - status
        - detail
      type: object
    ReservationCloseSummary:
      properties:
        capture_seq:
          description: >-
            This close's position in the reservation's capture sequence, oldest
            first.
          example: 1
          format: int64
          type: integer
        close_key:
          description: >-
            This close's identity. Pass it verbatim to the void endpoint to
            reverse this specific close — including when you no longer hold the
            Idempotency-Key you originally sent.
          example: ik:close_run_88f_final
          type: string
        closed:
          description: Whether this close terminated the reservation.
          type: boolean
        covered:
          description: >-
            Credits this close actually burned. Below used whenever the close
            priced past what the hold still had; the difference billed as cash.
          example: '80'
          type: string
        used:
          description: >-
            Credits this close was priced at. This — not covered — is what
            accumulates into the reservation's consumed.
          example: '80'
          type: string
        voided:
          description: >-
            Whether this close has been reversed. A voided close holds no
            credit, and its key cannot be reused — correct the work under a new
            identity.
          type: boolean
      required:
        - capture_seq
        - close_key
        - closed
        - covered
        - used
        - voided
      type: object
    ReservationIdentity:
      properties:
        event_name:
          description: The usage event that metric counts.
          example: inference_call
          type: string
        metric_id:
          description: A billable metric this hold's settles price against.
          example: mtr_tokens
          type: string
      required:
        - event_name
        - metric_id
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http

````