billable-metrics
List Metrics
List the platform's billable metrics, ordered by code: what usage is counted and
charged in (code, name, unit, category). The catalogue is the same for every
organization and curated by staff; archived metrics appear only with
include_archived=true.
query Parameters
include_archivedList Metrics › Responses
Successful Response
activecategoryThe five families every metric belongs to, and the whole of the list.
docs/features/billable-metrics.md fixes them there and says why they are
not staff-editable: "a category is a sentence about what the platform sells,
and the list of those sentences is this document's to hold". They are the top
level of every consumption picture and of every price list, so a sixth is a
decision written into the spec before it is a row anywhere. Ruled by the
owner (2026-09-15).
STORAGE was added 2026-09-18 (ADR 0040) for what it costs to keep something,
as distinct from something that happened: a gigabyte held for a month costs
the same whether it came from a call recording, a RAG document or an upload.
codecreated_atidnameupdated_atUsage Summary
Summarize the organization's billable usage over a time window. Use when showing what the organization is being charged for over a period. Changes nothing.
This is what an organization is charged for, not what a provider cost. Pass
agent_id to total only what one agent's conversations consumed.
from and to must each carry a UTC offset (2026-08-01T00:00:00Z or
2026-08-01T02:00:00+02:00). A timestamp without one is refused with 422 naming
the field, rather than being guessed at.
query Parameters
fromtometric_codeagent_idUsage Summary › Responses
Successful Response
amount^(?!^[-+.]*$)[+-]?0*… · requiredmetric_codetotal^(?!^[-+.]*$)[+-]?0*… · requiredGet Metric
Read one billable metric of the platform's catalogue by id: its code, name, unit, category and whether it is still active.
path Parameters
metric_idGet Metric › Responses
Successful Response
activecategoryThe five families every metric belongs to, and the whole of the list.
docs/features/billable-metrics.md fixes them there and says why they are
not staff-editable: "a category is a sentence about what the platform sells,
and the list of those sentences is this document's to hold". They are the top
level of every consumption picture and of every price list, so a sixth is a
decision written into the spec before it is a row anywhere. Ruled by the
owner (2026-09-15).
STORAGE was added 2026-09-18 (ADR 0040) for what it costs to keep something,
as distinct from something that happened: a gigabyte held for a month costs
the same whether it came from a call recording, a RAG document or an upload.
codecreated_atidnameupdated_at