Skip to content

Billing

Companions bills the exact provider cost of each run — there is no flat per-call rate. As a run executes, one ledger entry is written per model call; if a run fails, its charges are refunded. The billing surface lets you read your current balance and the full transaction ledger.

Amounts are in account currency units. Charges are negative (or 0 when the call cost nothing); top-ups and refunds are positive.

GET /v1/billing/balance

Return your current balance — a single-field response.

curl https://api.humx.ai/v1/billing/balance \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY"

import os, requests

r = requests.get(
    "https://api.humx.ai/v1/billing/balance",
    headers={"Authorization": f"ApiKey {os.environ['COMPANIONS_API_KEY']}"},
)
r.raise_for_status()
print(r.json()["balance"])

const res = await fetch("https://api.humx.ai/v1/billing/balance", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY}` },
});
const { balance } = await res.json();

const res = await fetch("https://api.humx.ai/v1/billing/balance", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY!}` },
});
const { balance } = (await res.json()) as { balance: number };

Response

200

Field Type Description
balance number Your current balance. 
{ "balance": 12.4830 }

Read your balance after a run

A completed completion job also carries your live balance on its terminal frame (details.balance_after), so you can track spend without a separate call.

GET /v1/billing/transactions

Return your ledger entries, newest first.

curl https://api.humx.ai/v1/billing/transactions \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY"

import os, requests

r = requests.get(
    "https://api.humx.ai/v1/billing/transactions",
    headers={"Authorization": f"ApiKey {os.environ['COMPANIONS_API_KEY']}"},
)
r.raise_for_status()
for tx in r.json():
    print(tx["created_at"], tx["kind"], tx["amount"], "→", tx["balance_after"])

const res = await fetch("https://api.humx.ai/v1/billing/transactions", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY}` },
});
const transactions = await res.json();

interface Transaction {
  id: string;
  kind: "topup" | "charge" | "refund" | "adjustment";
  amount: number;
  balance_after: number;
  run_id: string | null;
  description: string | null;
  created_at: string;
}

const res = await fetch("https://api.humx.ai/v1/billing/transactions", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY!}` },
});
const transactions = (await res.json()) as Transaction[];

Response

200 — an array of ledger entries (most recent 100).

Field Type Description
id string Transaction id.
kind string topup, charge, refund, or adjustment.
amount number Signed amount. Charges are negative, or 0 when the call cost nothing.
balance_after number Running balance immediately after this entry.
run_id string The run this charge belongs to, if any.
description string Human-readable note.
created_at string ISO-8601 timestamp. 
[
  {
    "id": "txn_88...",
    "kind": "charge",
    "amount": -0.0142,
    "balance_after": 12.4830,
    "run_id": "run_1a...",
    "description": "answer::main",
    "created_at": "2026-07-06T10:15:04Z"
  },
  {
    "id": "txn_87...",
    "kind": "topup",
    "amount": 20.0,
    "balance_after": 12.4972,
    "run_id": null,
    "description": "card top-up",
    "created_at": "2026-07-01T09:00:00Z"
  }
]

charge rows with amount: 0

A call that cost nothing — a free model, or a cost small enough to round away at four decimal places — still writes its ledger entry, with amount: 0 and a balance_after identical to the row before it. Nothing was taken from your balance; the entry is there so the call is visible rather than silently missing, and so its token counts are on record. Expect these rows if you use free models, and filter on amount != 0 when you only want the entries that moved money.

The ledger is append-only — corrections post as new refund or adjustment rows, never edits. Top-ups are added from your account dashboard.