Usage

What your organisation has spent, and what it has left.

When and why to call these: the usage guide.

Usage for your organisation

GET /v1/usage

Totals, a per-capability breakdown, a daily series and a per-key split over a window ending now, plus your plan and balance. units_seconds is seconds of audio generated; credits_micros is what was charged, and is null for a group nothing has priced yet.

A report — four aggregates over the window. Poll GET /v1/plan for the balance alone.

curl

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

Query parameters

Name	Type	Required	Description
days	integer		Window ending now 1–365. Default 30.

Responses

Status	Description
200	application/json — The report
400	The request could not be read: malformed JSON
401	Missing or invalid credentials
403	The key is valid but its scopes do not cover this capability — a key limited to tts gets this from /v1/images rather than a 401
422	The request failed validation
429	Rate limit exceeded

200 response body

Field	Type	Description
org_id	string
since	string (date-time)
until	string (date-time)
plan	OrgPlan or null	The organisation’s subscription and remaining credits, or null if it is not on a plan.
plan.plan_slug	string
plan.plan_name	string
plan.monthly_credits_micros	integer	What the plan grants each cycle.
plan.credit_balance_micros	integer	What is left: may exceed the grant after a manual adjustment, and be slightly negative inside the grace buffer.
plan.period_end	string (date-time)
total_requests	integer
total_seconds	number
by_capability	array of UsageSummary
by_capability[].capability	string
by_capability[].model	string or null
by_capability[].event_type	string or null
by_capability[].requests	integer
by_capability[].units_seconds	number
by_capability[].credits_micros	integer or null	What was charged; null when nothing in the group was priced.
by_capability[].unpriced_requests	integer	Requests in this group with no price recorded. Their credits are not in the sum, so a non-zero value here means the total is a floor.
daily	array of UsageDay	One entry per UTC day across the whole window, including days with no traffic. Gap-filled server-side so a chart can plot it directly rather than every client reinventing the same fill.
daily[].date	string (date)
daily[].requests	integer
daily[].units_seconds	number
by_key	array of UsageByKey	Which credential spent the quota, busiest first.
by_key[].api_key_id	string or null	Null once the key has been deleted
by_key[].name	string	Key label, or ‘Deleted key’ if it is gone
by_key[].requests	integer
by_key[].units_seconds	number
by_key[].credits_micros	integer or null	What was charged; null when nothing in the group was priced.
by_key[].unpriced_requests	integer	Requests in this group with no price recorded. Their credits are not in the sum, so a non-zero value here means the total is a floor.

Your plan and credit balance

GET /v1/plan

What plan your organisation is on, what it grants each cycle, what is left, and when the cycle ends. Two indexed lookups, so poll it freely — this is what to check before queueing a batch rather than learning from a 402.

credit_balance_micros may exceed monthly_credits_micros after a manual adjustment, and may be slightly negative inside the grace buffer. Null when the organisation has no subscription.

curl

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

Responses

Status	Description
200	application/json — The plan and balance, or null with no subscription
401	Missing or invalid credentials
403	The key is valid but its scopes do not cover this capability — a key limited to tts gets this from /v1/images rather than a 401
422	The request failed validation
429	Rate limit exceeded