Skip to main content
Some Humalike calls do real work on your behalf — generating or enhancing personas, validating a population, extracting a Social Learning profile, a Theory of Mind foresee, a Social Observability analysis, a Social Memory read. Those calls are billable and metered in credits. Plain writes (such as a Social Memory ingest) and reads of your own data are not billable. This page covers billing from a caller’s point of view: how your account is funded, how a call is priced, and the 402 Payment Required you get back when your balance can’t cover one.

​
Your credit account

Each Humalike account has a single credit balance, shared across every billable endpoint. The first billable call your account makes provisions the account and grants its initial allowance automatically — there is nothing to claim ahead of time. Every billable call after that draws against the same balance. To read your current usage at any time, call POST /v1/credits/projections/usage-summary.

​
How a call is priced

Billing is predictable and capped:
  • Priced before it runs. Each billable request is priced from its inputs (larger inputs and longer outputs cost more) and checked against your balance before any work begins.
  • Capped at that price. A call never costs more than the price computed up front. You pay for the work actually done, up to that ceiling.
  • Failed calls cost zero. If a request fails after it is accepted, nothing is charged.
Because the price is checked first, an underfunded request is rejected before any work is done — see below.

​
402 Payment Required

If your balance can’t cover the price of a request, the endpoint rejects it with HTTP 402 Payment Required before the call runs, using the standard error envelope:
402 Payment Required
{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "insufficient credits"
  }
}
Branch on error.code === "PAYMENT_REQUIRED" rather than on the message string. A 402 is a terminal answer to that exact request — do not retry it without changing something, because the same request will keep getting rejected for the same reason. To resolve it:
  • Top up your account from the Humalike dashboard, then retry the call.
  • Or shrink the request (a smaller transcript, a smaller count) so its price drops below your remaining balance.
When you see a 402, you can rely on it as a hard gate: the call did not run, and you were not charged.

​
Checking your usage

To pull your own billing data without leaving the API, see POST /v1/credits/projections/usage-summary. It returns 30-day totals, a per-product breakdown of where your credits went, and a 7-day daily series suitable for charting.