Credits

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). Every live draw must send either unique_id or the Idempotency-Key header and must reuse that identity on retries; otherwise the request is rejected before credits are consumed. A retry always replays the same credit decision, but re-publication of the underlying usage event depends on the feature’s backend tier: a durable (Postgres strict-reservation) feature’s retry republishes with the identical deduplicated usage identity, so no metering is lost; a soft/memorydb-tier feature’s retry returns the prior decision WITHOUT re-publishing — the original publish either already succeeded or must be recovered out of band. If a call returns retryable and the response indicates publication is not yet durable, retry with the SAME idempotency identity rather than assuming the usage event was recorded. 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.

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 '
{
  "account": "cust_abc123",
  "cost": "5",
  "event_name": "api_call",
  "feature": "llm_tokens",
  "properties": {},
  "reservation_id": "crt_abc123",
  "timestamp": "2026-04-01T10:00:00Z",
  "unique_id": "evt_abc123",
  "used": "3"
}
'

import requests

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

payload = {
    "account": "cust_abc123",
    "cost": "5",
    "event_name": "api_call",
    "feature": "llm_tokens",
    "properties": {},
    "reservation_id": "crt_abc123",
    "timestamp": "2026-04-01T10:00:00Z",
    "unique_id": "evt_abc123",
    "used": "3"
}
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({
    account: 'cust_abc123',
    cost: '5',
    event_name: 'api_call',
    feature: 'llm_tokens',
    properties: {},
    reservation_id: 'crt_abc123',
    timestamp: '2026-04-01T10:00:00Z',
    unique_id: 'evt_abc123',
    used: '3'
  })
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alguna.io/credits/track",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account' => 'cust_abc123',
    'cost' => '5',
    'event_name' => 'api_call',
    'feature' => 'llm_tokens',
    'properties' => [
        
    ],
    'reservation_id' => 'crt_abc123',
    'timestamp' => '2026-04-01T10:00:00Z',
    'unique_id' => 'evt_abc123',
    'used' => '3'
  ]),
  CURLOPT_HTTPHEADER => [
    "Alguna-Version: <alguna-version>",
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"account\": \"cust_abc123\",\n  \"cost\": \"5\",\n  \"event_name\": \"api_call\",\n  \"feature\": \"llm_tokens\",\n  \"properties\": {},\n  \"reservation_id\": \"crt_abc123\",\n  \"timestamp\": \"2026-04-01T10:00:00Z\",\n  \"unique_id\": \"evt_abc123\",\n  \"used\": \"3\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Alguna-Version", "<alguna-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alguna.io/credits/track")
  .header("Alguna-Version", "<alguna-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account\": \"cust_abc123\",\n  \"cost\": \"5\",\n  \"event_name\": \"api_call\",\n  \"feature\": \"llm_tokens\",\n  \"properties\": {},\n  \"reservation_id\": \"crt_abc123\",\n  \"timestamp\": \"2026-04-01T10:00:00Z\",\n  \"unique_id\": \"evt_abc123\",\n  \"used\": \"3\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Alguna-Version"] = '<alguna-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account\": \"cust_abc123\",\n  \"cost\": \"5\",\n  \"event_name\": \"api_call\",\n  \"feature\": \"llm_tokens\",\n  \"properties\": {},\n  \"reservation_id\": \"crt_abc123\",\n  \"timestamp\": \"2026-04-01T10:00:00Z\",\n  \"unique_id\": \"evt_abc123\",\n  \"used\": \"3\"\n}"

response = http.request(request)
puts response.read_body

{
  "allowed": true,
  "balance": "<string>",
  "covered_quantity": "<string>",
  "overflow_quantity": "<string>",
  "reservation_id": "crt_abc123",
  "reservation_expired": true
}

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

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

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

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

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

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

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 credit coverage; reservation-settlement mode. Mutually exclusive with feature/cost. Reservation settlement does not publish metered usage; send the raw usage event through /events before settling.

Example:

"crt_abc123"

timestamp

string<date-time> | null

Usage event timestamp (RFC3339); required in direct-consumption mode and must remain identical on retries.

Example:

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

unique_id

string | null

Stable dedupe identity for the recorded usage event. Live direct-consumption requests require either this field or the Idempotency-Key header; reuse the same identity on every retry.

Example:

"evt_abc123"

used

string | null

Credits actually used against the reservation; required in reservation-settlement mode (send "0" explicitly to settle as zero — omitting it is rejected, never treated as zero). Rejected when no matching raw usage stream is visible for the account and reservation window.

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

Create a customer portal sessionCreates a short-lived customer portal session and returns a signed URL the customer can use to access their billing portal. Sessions are single-use per token and expire after a short TTL.

⌘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 '
{
  "account": "cust_abc123",
  "cost": "5",
  "event_name": "api_call",
  "feature": "llm_tokens",
  "properties": {},
  "reservation_id": "crt_abc123",
  "timestamp": "2026-04-01T10:00:00Z",
  "unique_id": "evt_abc123",
  "used": "3"
}
'

import requests

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

payload = {
    "account": "cust_abc123",
    "cost": "5",
    "event_name": "api_call",
    "feature": "llm_tokens",
    "properties": {},
    "reservation_id": "crt_abc123",
    "timestamp": "2026-04-01T10:00:00Z",
    "unique_id": "evt_abc123",
    "used": "3"
}
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({
    account: 'cust_abc123',
    cost: '5',
    event_name: 'api_call',
    feature: 'llm_tokens',
    properties: {},
    reservation_id: 'crt_abc123',
    timestamp: '2026-04-01T10:00:00Z',
    unique_id: 'evt_abc123',
    used: '3'
  })
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alguna.io/credits/track",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account' => 'cust_abc123',
    'cost' => '5',
    'event_name' => 'api_call',
    'feature' => 'llm_tokens',
    'properties' => [
        
    ],
    'reservation_id' => 'crt_abc123',
    'timestamp' => '2026-04-01T10:00:00Z',
    'unique_id' => 'evt_abc123',
    'used' => '3'
  ]),
  CURLOPT_HTTPHEADER => [
    "Alguna-Version: <alguna-version>",
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"account\": \"cust_abc123\",\n  \"cost\": \"5\",\n  \"event_name\": \"api_call\",\n  \"feature\": \"llm_tokens\",\n  \"properties\": {},\n  \"reservation_id\": \"crt_abc123\",\n  \"timestamp\": \"2026-04-01T10:00:00Z\",\n  \"unique_id\": \"evt_abc123\",\n  \"used\": \"3\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Alguna-Version", "<alguna-version>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alguna.io/credits/track")
  .header("Alguna-Version", "<alguna-version>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account\": \"cust_abc123\",\n  \"cost\": \"5\",\n  \"event_name\": \"api_call\",\n  \"feature\": \"llm_tokens\",\n  \"properties\": {},\n  \"reservation_id\": \"crt_abc123\",\n  \"timestamp\": \"2026-04-01T10:00:00Z\",\n  \"unique_id\": \"evt_abc123\",\n  \"used\": \"3\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Alguna-Version"] = '<alguna-version>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account\": \"cust_abc123\",\n  \"cost\": \"5\",\n  \"event_name\": \"api_call\",\n  \"feature\": \"llm_tokens\",\n  \"properties\": {},\n  \"reservation_id\": \"crt_abc123\",\n  \"timestamp\": \"2026-04-01T10:00:00Z\",\n  \"unique_id\": \"evt_abc123\",\n  \"used\": \"3\"\n}"

response = http.request(request)
puts response.read_body

{
  "allowed": true,
  "balance": "<string>",
  "covered_quantity": "<string>",
  "overflow_quantity": "<string>",
  "reservation_id": "crt_abc123",
  "reservation_expired": true
}

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

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

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

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

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

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

API Reference

Examples

API Reference

Track credit consumption

Authorizations

Headers

Body

Response