> ## 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. # Reserve credits > Holds a block of credits up front for an operation whose exact cost is not yet known (for example an LLM call). Returns a reservation token that is settled later via POST /beta/credits/track with the amount actually used. A deny (insufficient available credit) is returned as `200 { allowed: false }`, not an HTTP error. When the credit gate is disabled for the organization, the endpoint fails closed: `200 { allowed: false, at_zero_action: "stop" }`. Send an Idempotency-Key header to make retries return the same reservation instead of opening a second hold. Failure handling: a timeout or `5xx` response is safe to retry with the SAME Idempotency-Key — the retry returns the original reservation instead of opening a second hold. A `409` means the key was already used with a different request body (or the pool already has an open reservation) and will never succeed as-is: do not retry it unchanged. On `429`, back off and retry after the indicated delay. ## OpenAPI ````yaml /api-reference/v2/specs/2026-04-01.json post /credits/check 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: Credit Notes - name: Credits - name: Customer Portal Sessions - name: Customers - name: Insights - 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: Wallet Grants - name: Wallets paths: /credits/check: post: tags: - Credits summary: Reserve credits description: >- Holds a block of credits up front for an operation whose exact cost is not yet known (for example an LLM call). Returns a reservation token that is settled later via POST /beta/credits/track with the amount actually used. A deny (insufficient available credit) is returned as `200 { allowed: false }`, not an HTTP error. When the credit gate is disabled for the organization, the endpoint fails closed: `200 { allowed: false, at_zero_action: "stop" }`. Send an Idempotency-Key header to make retries return the same reservation instead of opening a second hold. Failure handling: a timeout or `5xx` response is safe to retry with the SAME Idempotency-Key — the retry returns the original reservation instead of opening a second hold. A `409` means the key was already used with a different request body (or the pool already has an open reservation) and will never succeed as-is: do not retry it unchanged. On `429`, back off and retry after the indicated delay. operationId: check-credits parameters: - in: header name: Alguna-Version required: true schema: enum: - '2026-04-01' type: string - in: header name: Idempotency-Key schema: description: >- A unique string used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation. example: ik_a1b2c3d4e5f6 maxLength: 255 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CheckCreditsRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CheckCreditsResponse' description: Success headers: Idempotency-Key: description: Echo of the idempotency key provided in the request schema: type: string Idempotent-Replayed: description: >- Whether this response was replayed from a previous request (true) or freshly executed (false) schema: type: boolean '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 '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Conflict — a request with this idempotency key is currently being processed '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: CheckCreditsRequest: properties: account: description: Customer account ID or alias the credits belong to example: cust_abc123 type: string event_name: description: >- Usage event name, when the check should be resolved against a specific event's pricing context example: api_call nullable: true type: string feature: description: Feature (billable metric name) the credits are consumed against example: llm_tokens type: string properties: description: >- Event properties used to resolve customer-specific filter groups. Never a billing source of truth. type: object reserve: description: >- Amount of credits to hold up front. Omit for a cost-free preflight allow/deny check (no hold is opened). example: '100' nullable: true type: string required: - account - feature type: object CheckCreditsResponse: properties: allowed: description: Whether the requested amount is covered by available credit type: boolean at_zero_action: description: >- The feature's at-zero policy the caller should apply on a deny: stop (hard deny) or overflow (fall through to metered billing) example: overflow type: string balance: description: Available credit balance for the account (balance − reserved) type: string covered: description: Amount of the request covered by available credit type: string expires_at: description: >- When the opened hold expires. Present only when a reservation was opened. example: '2026-04-01T10:05:00Z' format: date-time nullable: true type: string reservation_id: description: >- Reservation token to settle later via /track. Empty unless a hold was opened (reserve). example: crt_abc123 type: string shortfall: description: >- Amount by which the request exceeded available credit (0 when fully covered) type: string required: - allowed - at_zero_action - balance - covered - reservation_id - shortfall type: object ErrorResponse: properties: detail: type: string status: format: int64 type: integer required: - status - detail type: object securitySchemes: bearerAuth: bearerFormat: API Key description: API key authentication. Pass your API key as a Bearer token. scheme: bearer type: http ````