Query conversation turn information
Updated
Retrieves conversation turn information and performance metrics.
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.
Note
You can query sessions within the last 7 days.
Path Parameters
appidstringThe App ID of the project.
agentIdstringThe agent instance ID you obtained after successfully calling join to Start a conversational AI agent.
Query Parameters
page_indexintegerThe page number. Starts from 1.
page_sizeintegerThe number of dialogue turns returned per page.
Response
-
If the returned status code is
200, the request was successful. -
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.
Response Body
The request was successful. The response body contains the result of the request.
agent_idstringThe unique identifier of the agent.
namestringThe name of the agent.
channelstringThe name of the RTC channel the agent joined.
total_turn_countintegerThe total number of dialogue turns in the current session.
paginationobjectPagination information.
page_indexintegerThe current page number; starts from 1.
total_pagesintegerThe total number of pages.
is_last_pagebooleanTrue if the current page is the last page.
turnsarray<object>A list of conversation turns for the agent session.
agent_idstringThe unique identifier of the agent.
channelstringThe name of the RTC channel the agent joined.
turn_idnumberThe sequential index of the turn within the session. Starts at 1.
startobjectDetails about the start of the turn.
start_atnumberThe Unix timestamp in milliseconds (UTC time) when the turn started.
typestringThe 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.
metadataobjectAdditional context about the turn start event. Included fields depend on the value of the type field.
speech_duration_msintegerThe duration of the user's voice input in milliseconds. Included only when type is voice_input.
interrupt_duration_msintegerThe minimum voice duration in milliseconds required to trigger an interruption. Included only when type is voice_input.
greeting_nthintegerThe index of the current greeting occurrence. Included only when type is greeting.
actionstringThe action taken in response to the silence timeout. Included only when type is silence_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.
transportstringThe transport protocol used to deliver the speak request. Included only when type is api_speak.
http: Delivered over HTTP.rtm: Delivered through the RTM Presence channel.
endobjectDetails about the end of the turn.
end_atnumberThe Unix timestamp in milliseconds (UTC time) when the turn ended.
typestringThe 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.
metadataobjectAdditional context about the turn end event. Included fields depend on the value of the type field.
playback_duration_msintegerThe audio playback duration in milliseconds. Included only when type is ok.
caused_bystringThe cause of the turn ending.
When type is interrupted, 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 type is ignored, 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.
transportstringThe transport protocol used to deliver the request. Included only when caused_by is api_speak or api_interrupt.
http: Delivered over HTTP.rtm: Delivered through the RTM Presence channel.
reasonstringThe error type. Included only when type is error.
LLM_REQUEST_ERR: LLM request error.INTERNAL_ERR: Internal error.
detailsstringAdditional error details. Included only when type is error.
metricsobjectLatency metrics for the turn.
e2e_latency_msintegerThe end-to-end latency in milliseconds for the turn.
segmented_latency_msarray<object>A breakdown of latency by segment.
namestringThe 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 LLM receives the request to when it 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 LLM receives a request until it outputs the first audio byte.transport: Network transmission delay in milliseconds. Not returned when the user is connected using the RTC Web SDK.
latencynumberThe latency in milliseconds for the segment.
Request examples
curl --request GET \ --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/turns \ --header 'Authorization: Basic <your_base64_encoded_credentials>'Response example
{ "agent_id": "A42Axxxxxxxxx37MT56J", "name": "support_agent_001", "channel": "test_channel", "total_turn_count": 250, "pagination": { "page_index": 1, "total_pages": 5, "is_last_page": false }, "turns": [ { "agent_id": "A42Axxxxxxxxx37MT56J", "channel": "test_channel", "turn_id": 1, "start": { "start_at": 1774579820147, "type": "greeting", "metadata": { "greeting_nth": 1 } }, "end": { "end_at": 1774579822412, "type": "interrupted", "metadata": { "caused_by": "api_interrupt", "transport": "rtm" } }, "metrics": { "e2e_latency_ms": 337, "segmented_latency_ms": [ { "name": "tts_ttfb", "latency": 337 } ] } } ]}