> ## 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. # Track credit consumption > Records credit consumption in one of two forms: draw an ad-hoc cost against the account's open block (feature + cost), or settle a prior reservation with the amount used (reservation_id + used). A deny is returned as `200 { allowed: false }`. When the credit gate is disabled for the organization, the endpoint fails closed with `200 { allowed: false }`. Settlement is idempotent — a retry with the same Idempotency-Key replays the recorded outcome instead of double-settling. Failure handling: a timed-out or `5xx` settlement is safe to retry with the SAME Idempotency-Key (the retry replays the recorded outcome). For draws, send `unique_id` (and the Idempotency-Key header) so a retried hard-stop draw replays instead of double-consuming. A `409` means the Idempotency-Key was already used with a different request body 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/track 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/track: post: tags: - Credits summary: Track credit consumption description: >- Records credit consumption in one of two forms: draw an ad-hoc cost against the account's open block (feature + cost), or settle a prior reservation with the amount used (reservation_id + used). A deny is returned as `200 { allowed: false }`. When the credit gate is disabled for the organization, the endpoint fails closed with `200 { allowed: false }`. Settlement is idempotent — a retry with the same Idempotency-Key replays the recorded outcome instead of double-settling. Failure handling: a timed-out or `5xx` settlement is safe to retry with the SAME Idempotency-Key (the retry replays the recorded outcome). For draws, send `unique_id` (and the Idempotency-Key header) so a retried hard-stop draw replays instead of double-consuming. A `409` means the Idempotency-Key was already used with a different request body and will never succeed as-is: do not retry it unchanged. On `429`, back off and retry after the indicated delay. operationId: track-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/TrackCreditsRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/TrackCreditsResponse' 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: TrackCreditsRequest: properties: account: description: Customer account ID or alias; direct-consumption mode example: cust_abc123 nullable: true type: string cost: description: >- Credits to draw for this call; direct-consumption mode, mutually exclusive with reservation_id/used. example: '5' nullable: true type: string event_name: description: >- Usage event name recorded for metering/overflow billing; direct-consumption mode example: api_call nullable: true type: string feature: description: Feature the credits are consumed against; direct-consumption mode example: llm_tokens nullable: true type: string properties: description: >- Event properties used to resolve customer-specific filter groups; direct-consumption mode. Never a billing source of truth. type: object reservation_id: description: >- Reservation token returned by /check, to settle; reservation-settlement mode. Mutually exclusive with feature/cost. example: crt_abc123 nullable: true type: string timestamp: description: >- Usage event timestamp (RFC3339). Defaults to now; direct-consumption mode. example: '2026-04-01T10:00:00Z' format: date-time nullable: true type: string unique_id: description: >- Organization-global idempotency key for the recorded usage event and credit draw; required in direct-consumption mode example: evt_abc123 nullable: true type: string used: description: >- Credits actually used against the reservation; reservation-settlement mode. example: '3' nullable: true type: string type: object TrackCreditsResponse: properties: allowed: description: Whether the consumption was covered by available credit type: boolean balance: description: Available credit balance for the account after this call type: string covered_quantity: description: Credit quantity covered by this call type: string overflow_quantity: description: Quantity not covered by credit that overflows to metered billing type: string reservation_expired: description: >- True when the referenced reservation had expired and the work was re-resolved as a fresh consume type: boolean reservation_id: description: >- Reservation this call settled or opened. Empty for a direct-consumption draw that opened no block. example: crt_abc123 type: string required: - allowed - balance - covered_quantity - overflow_quantity - reservation_id 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 ````