Credits and usage

Everything that spends is priced in credits, debited from your organisation’s balance. Your plan grants an allowance of credits each cycle. Two endpoints tell you where you stand:

curl

curl https://api.lumavox.ai/v1/plan -H "Authorization: Bearer $API_KEY"

Response

{
  "plan_slug": "pro",
  "plan_name": "Pro",
  "monthly_credits_micros": 100000000000,
  "credit_balance_micros": 73412500000,
  "period_end": "2026-11-01T00:00:00.000Z"
}

Both need a key with the usage:read scope (or the master key). It is a scope of its own so that a key handed out for one capability cannot see what the whole organisation spends.

Credit amounts are integers of micro-credits: 1000000 is one credit, so 73412500000 above is 73,412.5 credits. Integers add and compare exactly — divide by a million only to show a person. See Conventions.

Your balance: GET /v1/plan

Field	What it is
plan_slug, plan_name	the plan your organisation is on
monthly_credits_micros	what the plan grants each cycle
credit_balance_micros	what is left now
period_end	when the current cycle ends

The answer is null when your organisation has no subscription.

credit_balance_micros can be above monthly_credits_micros after a manual adjustment, and slightly below zero inside the plan’s grace buffer.

GET /v1/plan is cheap: poll it freely. Check it before queueing a batch, rather than finding out from a 402 halfway through.

Your usage: GET /v1/usage

A report over whole UTC days up to now — totals, a breakdown by capability, a daily series and a split by key, plus the same plan and balance as GET /v1/plan.

curl

curl "https://api.lumavox.ai/v1/usage?days=7" -H "Authorization: Bearer $API_KEY"

Query	What it does
days	the window: from midnight UTC days days ago until now, so its first day counts whole; 1 to 365, 30 by default

Field	What it is
since, until	the window: since is midnight UTC of its first day, until is now
plan	your plan and balance, or null with no subscription
total_requests, total_seconds	totals over the window
by_capability	one entry per capability, model and event type: requests, units_seconds, credits_micros
daily	one entry per UTC day across the whole window — days with no traffic included — with requests and units_seconds
by_key	which key spent what, busiest first; a deleted key shows as Deleted key with a null api_key_id

units_seconds is seconds of audio generated. credits_micros is what was charged, and is null for a group nothing has priced. A non-zero unpriced_requests means that group’s credits_micros leaves some requests out, so treat it as a floor.

The report is read from daily totals, a few rows a day; only by_key counts the window’s requests one by one. For the balance alone, call GET /v1/plan.

When you are charged

• Speech and transcription in the response are charged for the request itself: POST /v1/tts per thousand characters of text, POST /v1/stt per minute of audio.
• Queued jobs are charged when they are accepted and refunded in full if they fail. See queued jobs.
• Agents’ conversations are paid from the ephemeral key the end user holds. A key’s credit_limit_micros is set aside from your balance when it is minted, and what it does not spend comes back when it expires, runs out or is revoked. See end users and their keys.

Each endpoint’s reference says what its price depends on.

Out of credit: 402

When a charge takes your balance to the plan’s grace buffer or below, your organisation is suspended:

• every request made with your organisation’s API keys answers 402 insufficient_credits;
• every live ephemeral key is revoked, and what it had not spent comes back to the balance.

Response — 402

{
  "error": {
    "code": "insufficient_credits",
    "message": "This organisation has run out of credits. Usage resumes when the next monthly allowance is granted, or immediately if an administrator adds credits.",
    "request_id": "8f3c2a1b9d4e5f60",
    "issues": []
  }
}

It lifts by itself when credit arrives — the next cycle’s allowance, or credit an administrator adds — and nothing has to be re-enabled.

Minting an ephemeral key also answers 402 when the balance cannot cover the credit_limit_micros you asked to set aside, and so does a queued job whose estimate would take the balance past the grace buffer — refused before anything is charged. The buffer absorbs what was already running when credit ran out, never a job that would overdraw it on its own.

Your organisation’s members are emailed when the balance falls to a fifth of the monthly allowance, and again when it runs out.

Plan limits

Besides credit, your plan sets limits you can run into:

Limit	When you hit it
requests a minute, requests an hour, requests at the same time — for the organisation, and per capability	429 with Retry-After; see rate limits
unfinished videos at once	429 from POST /v1/videos, nothing charged
how many agents, voices and end users you hold	409 when you create one more
ephemeral keys: a key’s credit limit and lifetime, how many each end user may hold, how many you mint a minute, how much credit live keys may hold at once	422, 429 or 402 from POST /v1/ephemeral-keys; GET /v1/ephemeral-keys/limits lists them

The platform sets limits of its own besides your plan’s — the size of an upload, the tools on an agent, the unfinished generations at once, the ceilings on an ephemeral key: see Limits.

Related

• Limits
• Errors and limits
• Queued jobs
• API reference: usage