UsageEvent

One metered quantity of one Call (1.23.0): a stage, a Provider, a model and a unit with the quantity used and its amount rated at finalize. Identifiers, units and amounts only, never content.

An object with 22 fields.

Fields

Field	Type	Required	Description
`amount_micros`	integer or null	yes	The quantity times the unit price, rounded half up to whole micro-USD, frozen when the event was written (1.23.0); null when `rated` is false.
`analysis_id`	AnalysisId or null	no	The analysis whose result wrote the event (1.56.0), for the origin `analysis`; null for every other origin. Absent from an api before 1.56.0, which a reader treats as null.
`call_id`	CallId	yes	The Call whose finalize wrote the event (1.23.0).
`created_at`	Timestamp	yes	When the finalize transaction wrote the event (1.23.0); the spend counter counts a `live` event in the UTC calendar month of this instant.
`credential_source`	CredentialMode	no	Whose vendor account bore the quantity (1.28.0): `byok` when the Provider served it on the Organization's own credential, `platform` for every other event, the telephony and platform stages included. When a stage failed over, the events of each Provider that served it carry the source of that Provider's key. Until the platform fee of slice 2.5 exists, a `byok` event is rated with a unit price and an amount of 0, so it adds nothing to the spend counter or the cap; events frozen at 0 stay at 0. The api from 1.28.0 always sends it; a reader treats its absence as `platform`.
`environment`	Environment	yes	The environment of the Call (1.23.0). It is the flag of FR-usage-1: an event of a `test` Call is never billed and never counts towards the spend counter or the spend cap; only `live` events do.
`evaluation`	UsageEvaluationRef or null	no	For the origin `evaluation` (1.63.0): the role and the run, calibration or judgment that spent the quantity; null for every other origin. Absent from an api before 1.63.0, which a reader treats as null.
`finalize_id`	string (uuid)	yes	The finalize request that wrote the event (1.23.0). A finalize replayed with the same id returns the stored result and writes no event again. For an event whose `origin` is `call_record` (1.34.0) or `analysis` (1.56.0) there is no finalize request, and this is the id of the Call as a UUID, so it is unique to the Call and no worker's finalize id equals it.
`id`	UsageEventId	yes
`model`	string or null	yes	The model the price list keys the quantity by (1.23.0): the STT or language model, the TTS model (not the voice), or the carrier's plan item, which names the direction of a phone leg (origination for an inbound Call, termination for an outbound one). It is the model the Call's resolved chain names for the Provider. Null when the price does not depend on a model, as for the `call` unit.
`object`	`"usage_event"`	yes
`origin`	UsageEventOrigin	no	Who the quantity was measured from (1.34.0): `finalize` for an event the finalize request of the worker wrote, `call_record` for a leg the api measured from the Call's record when the Call ended with no finalize (hardening H-14), whose `finalize_id` is then the Call's own id. The api from 1.34.0 sends it; a reader treats its absence as `finalize`.
`price_id`	VendorPriceId or null	no	The vendor price row the event was rated by (1.38.0, workspace ADR 0086): the row in force for its stage, Provider, model and unit at the Call's admission instant; a `byok` event names the same row. Null when `rated` is false. Absent from an api before 1.38.0, where a reader treats it as null.
`price_list_version`	string	yes	The version of the price list the event was rated against at finalize (1.23.0). From 1.38.0 a label: the UTC date of the `effective_from` of the row named by `price_id`, which is the identity.
`provider`	CostProvider	yes	Who served the quantity (1.23.0): the Provider of the Turns that used it, `twilio` for the phone leg, `livekit` for the media server, or `vocal` for the `call` unit.
`quantity`	number	yes	How many units the Call used, summed over its Turns (1.23.0); minutes may be fractional, and the `call` unit is 1. The quantity is kept whether or not the event is rated.
`rated`	boolean	yes	True when the price list had a price for the stage, Provider, model and unit (1.23.0). False when it had none: `unit_price_micros` and `amount_micros` are then null, the quantity is kept, and the event adds nothing to any total.
`serving_agent_id`	AgentId or null	no	The Agent whose model chain spent the quantity (1.59.0): for the `llm` stage, the Call's own Agent or, after a handoff, the squad Agent its Turn's `stage_providers` entry names; null for every other stage. Absent from an api before 1.59.0, which a reader treats as the Call's Agent.
`serving_agent_version`	integer or null	no	The version of `serving_agent_id` that spent the quantity (1.59.0), the pinned version of the root or of the squad Agent, so a cost splits per serving Agent version; null when `serving_agent_id` is.
`stage`	CostStage	yes	What the quantity was used for (1.23.0): `stt`, `llm` and `tts` per Provider and model, `telephony` for the phone leg of a phone Call, and `platform` for the media server, the in-process models and the one `call` unit of each Call.
`unit`	CostUnit	yes	The unit the price list quotes the quantity in (1.23.0): `audio_minute` (audio streamed to STT), `token_in` and `token_out` (model tokens, every round of every Turn), `character` (text sent to TTS), `minute` (the phone leg from answer to end, or a platform item over the same span), or `call` (one per Call).
`unit_price_micros`	number or null	yes	The price of one unit in micro-USD as the price list held it when the event was written (1.23.0), fractional for tokens; null when `rated` is false. A later list never changes it.