Credits

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 /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 /events. An event feeding no credit-consuming metric is rejected with 422 and belongs there instead. Insufficient credit returns 200 with allowed: false.

The events’ own unique_ids identify the work, so a resent batch draws once. The SDKs send no automatic Idempotency-Key on this call and retry it without one. Send your own key only to replay a specific response; it then replaces the unique_ids as the identity, so reuse it when you resend the same work. The SDKs do not retry a 500. 409 means the identity is bound to different work. Back off on 429.

POST

credits

track

Track credit consumption

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"
}
'

import requests

url = "https://api.alguna.io/credits/track"

payload = {
    "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"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.alguna.io/credits/track', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

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 that makes a retried write safe. If you send the same request with the same key within 24 hours, the API returns the stored response and does not run the request again. A 5xx or 429 response is not stored, so a retry with that key runs the request again.

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.

Maximum array length: 100

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"

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

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"

⌘I

Track credit consumption

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"
}
'

import requests

url = "https://api.alguna.io/credits/track"

payload = {
    "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"
}
headers = {
    "Alguna-Version": "<alguna-version>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Alguna-Version': '<alguna-version>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.alguna.io/credits/track', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

{
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>"
}

API Reference

Examples

SDKs

API Reference

Webhooks

Track credit consumption

Authorizations

Headers

Body

Response