Track credit consumption

Records usage and charges credit for it. The request carries no credit amount: send what happened, and the response’s charges carry what it priced to per metric, with totals as the sum.

Two shapes. A direct draw (account + events) charges against the account’s current credit. A settlement (reservation_id + events + close) closes a hold opened by /beta/credits/check, pricing each metric at the rate frozen when the hold opened. One payload can feed several credit-consuming metrics, and the draw is all-or-nothing: a refusal for one metric leaves every metric uncharged.

Events sent here are both metered and charged, so do not also send them to POST /beta/events. An event feeding no credit-consuming metric is rejected with 422 and belongs there instead. Identity comes from the Idempotency-Key, or from the events’ own unique_ids when no key is sent; reuse it when retrying. Insufficient credit returns 200 with allowed: false. 409 means the identity is bound to different work. Back off on 429.

POST /credits/track

Track credit consumption

cURL

curl --request POST \
  --url https://api.alguna.io/credits/track \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "event_name": "agent_step",
      "unique_id": "run_88f_step1",
      "properties": {},
      "timestamp": "2026-04-01T10:00:00Z"
    }
  ],
  "account": "cust_abc123",
  "close": true,
  "on_envelope_exceeded": "record",
  "reservation_id": "crt_abc123"
}
'

200

{
  "allowed": true,
  "balances": [
    {
      "available": "985",
      "credit_type": "units",
      "filtered": true,
      "metric_ids": [
        "[\"mtr_1\"]"
      ],
      "ledger_id": "crl_abc",
      "scope": {
        "level": "account",
        "filters": {},
        "subscription_id": "sub_123"
      }
    }
  ],
  "charges": [
    {
      "covered": "15",
      "credits": "15",
      "ledger_id": "crl_acct",
      "metric_id": "mtr_tokens",
      "overflow": "0",
      "quantity": "1500",
      "uncovered_quantity": "0"
    }
  ],
  "reservation_id": "crt_abc123",
  "reservation_open": true,
  "reservation_remaining": "0",
  "totals": {
    "covered": "23",
    "overflow": "0",
    "uncovered_metric_quantity": "0",
    "used": "23"
  },
  "at_zero_action": "stop",
  "envelope_exceeded": true,
  "events_accepted": 3,
  "events_priced": 2,
  "reservation_expired": true,
  "reservation_expires_at": "2026-04-01T10:20:00Z"
}

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

events · object[] · required

The usage being recorded, up to 100 events. The amount charged is computed from these against whichever billable metrics count them; there is no credit amount in the request. On a settlement, an empty array with close: true releases the whole reservation, charging nothing, which is the recovery when work is abandoned.

Show child attributes

account · string | null

Customer account ID or alias; direct-draw mode. Required unless reservation_id is set, where the account comes from the reservation.

Example:

"cust_abc123"

close · boolean | null

Whether this is the final call for the reservation. Required whenever reservation_id is set: there is no safe default, since true would end runs that meant to continue and false would leak reservations until they expire. The reservation also closes on its own if the events consume everything held. Not valid on a direct draw.

Example:

true

on_envelope_exceeded · enum<string> | null

What to do when a settle cannot be fully covered by credit on a metric that stops at zero — either because it prices past the reservation's authorized hold, or because credit ran out before a late settle arrived. "reject" (the default) refuses the settle, burning and recording nothing. "record" burns what is available and reports the remainder in the charges' overflow, deliberately weakening a hard stop you configured. Reservation-settlement mode only. The refusal body's reason says which condition fired: adding credit resolves coverage_shortfall, but not envelope_exceeded, whose limit is the hold's size.

Available options: reject, record

Example:

"record"

reservation_id · string | null

Reservation token returned by /check, to close it; reservation-settlement mode. Mutually exclusive with account. The events sent alongside are both metered and charged, so do not send them to /events as well.

Example:

"crt_abc123"

Response

200

application/json

Success

allowed · boolean · required

Whether the consumption was covered by available credit

balances · object[] · required

Per-metric, per-ledger availability after this call — one entry per ledger, so a single-ledger payload returns one. Always an array, but empty when no availability was resolved to report, including every response served while the organization's gate is disabled. Check the length before indexing.

Show child attributes

charges · object[] · required

One entry per metric this call's events fed: quantity counted, credits priced, credit covered, overflow to cash, and the ledger that paid. Always an array, length 1 in the ordinary single-metric case.

Show child attributes

reservation_id · string · required

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

Example:

"crt_abc123"

reservation_open · boolean · required

Whether the reservation is still open and can be settled again. False even on a close: false call whose events consumed everything held — there is no envelope left to keep open.

reservation_remaining · string · required

Credits still held by this reservation and available to later calls.

Example:

"0"

totals · object · required

The charges summed. Derived from charges — the breakdown is authoritative.

Show child attributes

at_zero_action · string

The reservation's at-zero policy, reported when the envelope was exceeded.

Example:

"stop"

envelope_exceeded · boolean

True when the events priced past the reservation's remaining hold and were recorded anyway because on_envelope_exceeded was record. Worth alarming on for a feature that stops at zero.

events_accepted · integer<int64>

How many events this call recorded.

Example:

3

events_priced · integer<int64>

How many of those events at least one metric's filters counted toward a charge. A lower number than events_accepted means some events did not qualify, without exposing the filter itself.

Example:

2

reservation_expired · boolean

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

reservation_expires_at · string<date-time> | null

When the still-open reservation now expires. Each accepted call extends this, so a long run that reports as it goes never expires mid-flight. Absent once the reservation closes.

Example:

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