TurnMetrics
The measurements of one Turn, without its text.
An object with 41 fields.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
cost | TurnCost or null | no | The Turn's share of the Call's cost estimate; null when the Call was not rated. Added in 1.5.0. From 1.29.0 (workspace ADR 0078, decision 7) the api sends it, in the Call and Turns reads, only to a reader that holds usage:read and omits it for any other, such as the viewer role; a reader treats its absence as null. |
cut_source | TurnCutSource or null | no | How the reply was cut when the caller interrupted it (1.38.0, board #116): vendor_timestamps or estimate, which agrees with truncation_estimated. Null when the reply was not cut; a worker before 1.38.0 sends none, and a reader treats its absence as null. |
decision_failover | boolean or null | no | True when a secondary Provider answered under its own thresholds. Added in 1.58.0: a reader treats its absence as null. |
decision_ms | integer or null | no | From the decision request to its verdict, a measurement; null when no lane ran. Added in 1.58.0: a reader treats its absence as null. |
decision_status | DecisionStatus or null | no | The status of the Turn's last verdict; null when no lane ran. Added in 1.58.0: a reader treats its absence as null. |
decision_wait_ms | integer or null | no | How long before_model waited for a routing verdict, inside model_first_token; null when no routing set ran. Added in 1.58.0: a reader treats its absence as null. |
echo_text_dropped | integer or null | no | Caller transcript segments the text-level echo check dropped as the Agent's own words; null on a leg without the check (web and app). Added in 1.20.0: a reader treats its absence as null. |
ended_at | Timestamp | yes | |
endpoint_fallback | boolean | yes | The end of turn came from the silence fallback, not the turn detector. |
endpoint_ms | integer or null | yes | Stage endpoint: last caller speech frame to the end-of-turn decision. |
first_chunk_wait_ms | integer or null | no | The chunker's wait for the first speakable chunk, from the first model token; included in tts_first_byte_ms. Null when no model reply was spoken. Added in 1.20.0: a reader treats its absence as null. |
interrupted | boolean | yes | The caller interrupted the reply. |
interruption_candidates | integer or null | no | Caller speech starts while the Agent was speaking, each a candidate interruption. Added in 1.20.0: a reader treats its absence as null. |
interruptions_suppressed | InterruptionsSuppressed or null | no | Null when the worker counted none. Added in 1.20.0: a reader treats its absence as null. |
language | LanguageTag | yes | |
leading_silence_ms | integer or null | yes | Leading silence in the first reply audio; included in tts_first_byte_ms. |
llm_provider | ProviderId or null | yes | |
model_first_token_ms | integer or null | yes | Stage model_first_token: wait for the first model token. |
object | "turn" | yes | |
policy_metrics | TurnPolicyMetrics or null | no | The hook timings of the Turn (1.48.0, roadmap slice 2.2): per hook dispatched in the Turn, the dispatches, the Policies evaluated and fired, and the summed and longest time in microseconds, with the Turn's pre-checks. Null when the worker counted none, as a worker before 1.48.0 does; a reader treats its absence as null. |
render_hmac | string or null | no | HMAC-SHA256 of the instructions composed for the Turn's first model request (1.59.0, the field the worker reports from 1.58.0), so a reader compares two Turns' prompts without either text; null when none was composed or no key was held, and absent from an api before 1.59.0. |
retrieval_ms | integer or null | no | How long before_model waited for the context retrievals of the Turn, the longest of them, a measurement in milliseconds; null when no context binding applied. Added in 1.53.0: a reader treats its absence as null. |
retrieval_passages | integer or null | no | How many passages entered the model request as keyed context entries; null when no context binding applied. Added in 1.53.0: a reader treats its absence as null. |
retrieval_skipped | boolean or null | no | True when a context retrieval of the Turn missed its budget_ms or failed and the request went out without its passages; null when no context binding applied. Added in 1.53.0: a reader treats its absence as null. |
route_abort | boolean or null | no | True when a verdict that changed the speaker state landed while the model request had produced nothing yet: the request was closed at its first chunk with text or a Tool call, before any audio (the reading of 1.59.0), and a request was composed for the new state; its tokens are still metered. Added in 1.58.0: a reader treats its absence as null. |
route_late | boolean or null | no | True when a verdict routed after the request produced its first chunk: the machine stepped when the verdict landed (the reading of 1.59.0), and the new state reached the model from the next request. Added in 1.58.0: a reader treats its absence as null. |
seq | integer | yes | The Turn number in the Call; 0 is the greeting, whose caller stages are null. |
speakers | array or null | no | The Agents whose model produced the reply, in order, with the version each ran: more than one after a handoff inside the Turn; null when only the root Agent spoke. Added in 1.58.0: a reader treats its absence as null. |
stage_providers | TurnStageProviders or null | no | Which Providers served each stage of the Turn, in the order they served it (1.35.0, board #94). Absent or null means one Provider served every stage throughout, the one stt_provider, llm_provider or tts_provider names, as in every Turn before 1.35.0; a stage that is absent from the object was served by one Provider too. A stage is listed when its chain switched Provider during the Turn, and may be listed with one entry. Each entry names the Provider, the model, the id of the credential key it ran on (a plk_ or pcr_ id, null when the worker holds no key id for it; never the secret or its hint), the loss that moved the stage to it, and the quantity it handled in the unit the Usage events rate the stage by. To rate the Turn, take the quantities of a stage's entries as parts of the Turn's usage quantities for that stage and rate each part under its entry's Provider and model; rate any remainder, a quantity of usage that the entries do not account for, under the Provider that stt_provider, llm_provider or tts_provider names, as a Turn without this field is rated. |
started_at | Timestamp | yes | |
states | array or null | no | The stable speaker states of the Turn in order: the one it began in and each one entered during it; null for the implicit machine. Added in 1.58.0: a reader treats its absence as null. |
stt_final_ms | integer or null | yes | Stage stt_final: further wait for the final transcript. |
stt_provider | ProviderId or null | yes | |
tool_metrics | TurnToolMetrics or null | no | The Tool loop of the Turn (1.49.0, roadmap slice 2.3): rounds, invocations, failures, their time and the tool_loop_cap tag. Null when the Turn ran no Tool; a worker before 1.49.0 sends none, and a reader treats its absence as null. |
transport_ms | integer or null | yes | Stage transport, from an external measurement only. |
truncation_estimated | boolean | yes | The heard reply text was cut at an estimated point after an interruption. |
tts_first_byte_ms | integer or null | yes | Stage tts_first_byte: wait for the first audible reply frame. |
tts_provider | ProviderId or null | yes | |
unattributed_ms | integer or null | yes | Time an external measurement could not attribute to a stage. |
usage | TurnUsage or null | no | The quantities the worker counted; null when it reported none. Added in 1.5.0: the api always sends it, and a reader treats its absence as null. |
voice_to_voice_internal_ms | integer or null | yes | The sum of the four worker stages. |