Skip to main content
POST
Track credit consumption

Authorizations

Authorization
string
header
required

API key authentication. Pass your API key as a Bearer token.

Headers

Alguna-Version
enum<string>
required
Available options:
2026-04-01
Idempotency-Key
string

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.

Maximum string length: 255
Example:

"ik_a1b2c3d4e5f6"

Body

application/json
account
string | null

Customer account ID or alias; direct-consumption mode

Example:

"cust_abc123"

cost
string | null

Credits to draw for this call; direct-consumption mode, mutually exclusive with reservation_id/used.

Example:

"5"

event_name
string | null

Usage event name recorded for metering/overflow billing; direct-consumption mode

Example:

"api_call"

feature
string | null

Feature the credits are consumed against; direct-consumption mode

Example:

"llm_tokens"

properties
object

Event properties used to resolve customer-specific filter groups; direct-consumption mode. Never a billing source of truth.

reservation_id
string | null

Reservation token returned by /check, to settle; reservation-settlement mode. Mutually exclusive with feature/cost.

Example:

"crt_abc123"

timestamp
string<date-time> | null

Usage event timestamp (RFC3339). Defaults to now; direct-consumption mode.

Example:

"2026-04-01T10:00:00Z"

unique_id
string | null

Organization-global idempotency key for the recorded usage event and credit draw; required in direct-consumption mode

Example:

"evt_abc123"

used
string | null

Credits actually used against the reservation; reservation-settlement mode.

Example:

"3"

Response

Success

allowed
boolean
required

Whether the consumption was covered by available credit

balance
string
required

Available credit balance for the account after this call

covered_quantity
string
required

Credit quantity covered by this call

overflow_quantity
string
required

Quantity not covered by credit that overflows to metered billing

reservation_id
string
required

Reservation this call settled or opened. Empty for a direct-consumption draw that opened no block.

Example:

"crt_abc123"

reservation_expired
boolean

True when the referenced reservation had expired and the work was re-resolved as a fresh consume