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; 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.
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"
  }
]

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