Query conversation turn information
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/turnsAfter a conversation with the agent ends, use this endpoint to query the conversation turn information, including the start information, end information, and performance metrics of each conversation turn.
You can query sessions within the last 7 days.
Request
Path parameters
The App ID of the project.
The agent instance ID you obtained after successfully calling join to Start a conversational AI agent.
Response
-
If the returned status code is
200, the request was successful.response
- turns array
A list of conversation turns for the agent session.
Show propertiesHide properties
- agent_id string
The unique identifier of the agent.
- channel string
The name of the RTC channel the agent joined.
- turn_id number
The sequential index of the turn within the session. Starts at
1. - start object
Details about the start of the turn.
Show propertiesHide properties
- start_at number
The Unix timestamp in milliseconds (UTC time) when the turn started.
- type string
Possible values:
voice_input,greeting,silence_timeout,api_speakThe type of event that initiated the turn.
voice_input: The turn was initiated by user voice input.greeting: The turn was initiated by an agent greeting.silence_timeout: The turn was initiated due to a silence timeout.api_speak: The turn was initiated by a call to the speak API.
- metadata object
Additional context about the turn start event. Included fields depend on the value of the
typefield.Show propertiesHide properties
- speech_duration_ms integer
The duration of the user's voice input in milliseconds. Included only when
typeisvoice_input. - interrupt_duration_ms integer
The minimum voice duration in milliseconds required to trigger an interruption. Included only when
typeisvoice_input. - greeting_nth integer
The index of the current greeting occurrence. Included only when
typeisgreeting. - action string
The action taken in response to the silence timeout. Included only when
typeissilence_timeout.speak: Plays the silence prompt message to the user.think: Appends the silence message to the conversation context and passes it to the LLM.
- transport string
The transport protocol used to deliver the speak request. Included only when
typeisapi_speak.http: Delivered over HTTP.rtm: Delivered through the RTM Presence channel.
- end object
Details about the end of the turn.
Show propertiesHide properties
- end_at number
The Unix timestamp in milliseconds (UTC time) when the turn ended.
- type string
Possible values:
ok,interrupted,ignored,errorThe type of event that ended the turn.
ok: The turn ended normally.interrupted: The turn was interrupted.ignored: The turn was ignored.error: The turn ended due to an error.
- metadata object
Additional context about the turn end event. Included fields depend on the value of the
typefield.Show propertiesHide properties
- playback_duration_ms integer
The audio playback duration in milliseconds. Included only when
typeisok. - caused_by string
The cause of the turn ending.
When
typeisinterrupted, possible values are:start_of_speech: A new voice input interrupted the turn.api_speak: The turn was interrupted by a call to the speak API.api_interrupt: The turn was interrupted by a call to the interrupt API.api_leave: The turn was interrupted because the agent left the channel.
When
typeisignored, possible values are:semantic: The turn was ignored because semantic end-of-speech detection determined no response was required. Applies whenturn_detection.config.end_of_speech.modeis set tosemantic.keywords: The turn was ignored because the start keyword was not detected. Applies whenturn_detection.config.start_of_speech.modeis set tokeywords.disable: The turn was ignored because interruption is disabled for this turn.
- transport string
The transport protocol used to deliver the request. Included only when
caused_byisapi_speakorapi_interrupt.http: Delivered over HTTP.rtm: Delivered through the RTM Presence channel.
- reason string
The error type. Included only when
typeiserror.LLM_REQUEST_ERR: LLM request error.INTERNAL_ERR: Internal error.
- details string
Additional error details. Included only when
typeiserror.
- metrics object
Latency metrics for the turn.
Show propertiesHide properties
- e2e_latency_ms integer
The end-to-end latency in milliseconds for the turn.
- segmented_latency_ms array
A breakdown of latency by segment.
Show propertiesHide properties
- name string
The name of the latency segment.
When the LLM input modality is
text, the returned segments are:algorithm_processing: Algorithm processing delay.asr_ttlw: The ASR Time To Last Word (TTLW) in milliseconds. Represents the delay from when the user finishes speaking to when the ASR module outputs the last word.llm_ttft: The LLM Time To First Token (TTFT) in milliseconds. Represents the delay from when the user finishes speaking to when the LLM outputs the first token.llm_ftfs: The LLM First Token To First Sentence (FTFS) in milliseconds. Represents the delay from when the LLM outputs the first token to when it outputs the first complete sentence.tts_ttfb: The TTS Time To First Byte (TTFB) in milliseconds. Represents the delay from when the TTS module receives a text request to when it outputs the first audio byte.transport: Network transmission delay in milliseconds. Not returned when the user is connected using the RTC Web SDK.
When the LLM input modality is
audio, the returned segments are:algorithm_processing: Algorithm processing delay.asr_ttlw: The ASR Time To Last Word (TTLW) in milliseconds. Represents the delay from when the user finishes speaking to when the ASR module outputs the last word.llm_ttfa: The LLM Time To First Audio Byte (TTFA) in milliseconds. Represents the delay from when the user finishes speaking to when the LLM outputs the first audio byte.transport: Network transmission delay in milliseconds. Not returned when the user is connected using the RTC Web SDK.
- latency number
The latency in milliseconds for the segment.
-
If the returned status code is not
200, the request failed. The response body includes the error code and description. Refer to status codes to understand the possible reasons for failure.