Reserve credits

Prices work before it happens and, optionally, reserves credit for it. The request carries no credit amount: describe the work as the events it will produce, and the response’s charges say what it prices to per metric.

Send events alone to get a price with nothing recorded. Send reserve to open a hold, then close it with POST /beta/credits/track. "reserve": {} with events holds enough for exactly that work; "reserve": {"max_quantity": "100000"} with event_name holds a ceiling in metric units. An Idempotency-Key is required whenever reserve is set. Each metric is held at the rate frozen when the hold opened, and the hold expires after 15 minutes unless ttl_seconds asks for longer (maximum 4 hours).

Only credit-gated metrics are accepted: an event feeding no credit-consuming metric is rejected with 422 and belongs on POST /beta/events. Insufficient credit returns 200 with allowed: false; an allowed: true response carrying no reservation_id opened no hold. Retry timeouts and 5xx with the same key. 409 means the key is bound to a different reservation. Back off on 429, which also covers a ledger at its concurrent-hold cap.

POST /credits/check

Reserve credits

cURL

curl --request POST \
  --url https://api.alguna.io/credits/check \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "cust_abc123",
  "event_name": "api_call",
  "events": [
    {
      "event_name": "agent_step",
      "unique_id": "run_88f_step1",
      "properties": {},
      "timestamp": "2026-04-01T10:00:00Z"
    }
  ],
  "properties": {},
  "reserve": {
    "max_quantity": "100000"
  },
  "ttl_seconds": 3600
}
'

200

{
  "allowed": true,
  "at_zero_action": "overflow",
  "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",
  "totals": {
    "covered": "23",
    "overflow": "0",
    "uncovered_metric_quantity": "0",
    "used": "23"
  },
  "expires_at": "2026-04-01T10:05: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

account · string · required

Customer account ID or alias the credits belong to

Example:

"cust_abc123"

event_name · string

The usage event the work will produce. This is what resolves which billable metrics the check is against — you name what you are about to do, not which metric counts it. An event that feeds no credit-consuming metric is rejected with 422 — that usage belongs on POST /beta/events; an event feeding several credit-consuming metrics is checked (and held) against all of them at once. Optional when events carries the sample; required for reserve.max_quantity.

Example:

"api_call"

events · object[]

A sample of the work about to happen. The response's charges carry what that work would cost per metric, priced exactly as /track would price it. Nothing is recorded and no credit moves — this is how you learn a price without performing the work. With reserve: {}, the hold is sized to exactly these events.

Show child attributes

properties · object

Event properties used to resolve customer-specific filter groups for this check. Not a billing input: this call records nothing.

reserve · object | null

Open a durable hold alongside the check. An object, never a number: send {} to hold enough for exactly the events in this request, or {"max_quantity": "…"} with event_name for an open-ended ceiling in metric units. The old numeric credit-amount form is rejected — the request no longer carries credit amounts anywhere. Omit for a cost-free preflight or quote (no hold is opened). Requires an Idempotency-Key.

Show child attributes

ttl_seconds · integer<int64> | null

How long the hold stays open, in seconds. Defaults to 900 (15 minutes) and cannot exceed 14400 (4 hours), the maximum lifetime any hold may reach. Use it for a run that cannot report progress as it goes; a run that can should send partial settlements to /track instead, since each one slides this same TTL forward. Requires reserve. Not part of idempotency identity: a retry under the same Idempotency-Key replays the original hold with its original expires_at, whatever ttl_seconds it now carries.

Required range: 1 <= x <= 14400

Example:

3600

Response

200

application/json

Success

allowed · boolean · required

Whether the named work is covered by available credit (and, with reserve, whether a hold was opened).

at_zero_action · string · required

The at-zero policy the caller should apply on a deny: stop (hard deny) or overflow (fall through to metered billing). When the work feeds several metrics with differing policies, the strictest (stop) is reported.

Example:

"overflow"

balances · object[] · required

Per-metric, per-ledger availability — one entry per ledger, so a single-ledger account returns one. Always an array, but not always a populated one: it is empty when no availability was resolved to report, which is every response the gate could not read balances for (a back-pressure fail-open, a failed post-hold refresh, a failed report behind a deny) and 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 the named work feeds: what the sampled events (or the max_quantity ceiling) price to per metric, and what a hold covers of it. Where no hold was opened — a quote, a denied reserve, a degraded fail-open — covered is zero and overflow carries the whole priced amount as the cash exposure of the described work. A check that named work but sampled none prices to zero throughout. Always an array, length 1 in the single-metric case.

Show child attributes

reservation_id · string · required

Reservation token to settle later via /track. Empty unless a hold was opened (reserve).

Example:

"crt_abc123"

totals · object · required

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

Show child attributes

expires_at · string<date-time> | null

When the opened hold expires. Present only when a reservation was opened.

Example:

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