# Query conversation turn information (/en/api-reference/api-ref/conversational-ai/turns)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Retrieves conversation turn information and performance metrics.

- OpenAPI: /openapi/conversational-ai/rest-api.en.yaml
- Operation ID: get-turns
- Method: GET
- Path: /v2/projects/{appid}/agents/{agentId}/turns
- Endpoint: https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/turns

## Servers

- https://api.agora.io/api/conversational-ai-agent

After 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.


:::info[Note]
You can query sessions within the last 7 days.
:::

## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `agentId` (path, required, string) - The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join).
- `page_index` (query, optional, integer) - The page number. Starts from 1.
  - Default: `1`
- `page_size` (query, optional, integer) - The number of dialogue turns returned per page.
  - Default: `50`

## Request body

No request body.

## Request examples

### curl

```bash
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>'
```

### Python

```python
import requests

    url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/turns"

    headers = {
        "Authorization": "Basic <your_base64_encoded_credentials>",
        "Content-Type": "application/json"
    }

    response = requests.get(url, headers=headers)
    print(response.text)
```

### Node.js

```javascript
const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/turns';

    const options = {
      method: 'GET',
      headers: {
        'Authorization': 'Basic <your_base64_encoded_credentials>',
        'Content-Type': 'application/json'
      }
    };

    fetch(url, options)
      .then(res => res.json())
      .then(json => console.log(json))
      .catch(err => console.error(err));
```


### 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](/en/api-reference/api-ref/conversational-ai/status-codes) to understand the possible reasons for failure.


## Responses

### 200

The request was successful. The response body contains the result of the request.

- `agent_id` (string) - The unique identifier of the agent.
- `name` (string) - The name of the agent.
- `channel` (string) - The name of the RTC channel the agent joined.
- `total_turn_count` (integer) - The total number of dialogue turns in the current session.
- `pagination` (object) - Pagination information.
  - `pagination.page_index` (integer) - The current page number; starts from 1.
  - `pagination.total_pages` (integer) - The total number of pages.
  - `pagination.is_last_page` (boolean) - True if the current page is the last page.
- `turns` (array) - A list of conversation turns for the agent session.
  - `turns.items` (object)
    - `turns.items.agent_id` (string) - The unique identifier of the agent.
    - `turns.items.channel` (string) - The name of the RTC channel the agent joined.
    - `turns.items.turn_id` (number) - The sequential index of the turn within the session. Starts at `1`.
    - `turns.items.start` (object) - Details about the start of the turn.
      - `turns.items.start.start_at` (number) - The Unix timestamp in milliseconds (UTC time) when the turn started.
      - `turns.items.start.type` (string) - The 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.
        - Allowed: `voice_input` | `greeting` | `silence_timeout` | `api_speak`
      - `turns.items.start.metadata` (object) - Additional context about the turn start event. Included fields depend on the value of the `type` field.
        - `turns.items.start.metadata.speech_duration_ms` (integer) - The duration of the user's voice input in milliseconds. Included only when `type` is `voice_input`.
        - `turns.items.start.metadata.interrupt_duration_ms` (integer) - The minimum voice duration in milliseconds required to trigger an interruption. Included only when `type` is `voice_input`.
        - `turns.items.start.metadata.greeting_nth` (integer) - The index of the current greeting occurrence. Included only when `type` is `greeting`.
        - `turns.items.start.metadata.action` (string) - The 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.
        - `turns.items.start.metadata.transport` (string) - The 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.
    - `turns.items.end` (object) - Details about the end of the turn.
      - `turns.items.end.end_at` (number) - The Unix timestamp in milliseconds (UTC time) when the turn ended.
      - `turns.items.end.type` (string) - The 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.
        - Allowed: `ok` | `interrupted` | `ignored` | `error`
      - `turns.items.end.metadata` (object) - Additional context about the turn end event. Included fields depend on the value of the `type` field.
        - `turns.items.end.metadata.playback_duration_ms` (integer) - The audio playback duration in milliseconds. Included only when `type` is `ok`.
        - `turns.items.end.metadata.caused_by` (string) - The 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 when [`turn_detection.config.end_of_speech.mode`](/en/api-reference/api-ref/conversational-ai/join#request-body-properties-turn-detection-config-end-of-speech-mode) is set to `semantic`.
- `keywords`: The turn was ignored because the start keyword was not detected. Applies when [`turn_detection.config.start_of_speech.mode`](/en/api-reference/api-ref/conversational-ai/join#request-body-properties-turn-detection-config-start-of-speech-mode) is set to `keywords`.
- `disable`: The turn was ignored because interruption is disabled for this turn.
        - `turns.items.end.metadata.transport` (string) - The 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.
        - `turns.items.end.metadata.reason` (string) - The error type. Included only when `type` is `error`.

- `LLM_REQUEST_ERR`: LLM request error.
- `INTERNAL_ERR`: Internal error.
        - `turns.items.end.metadata.details` (string) - Additional error details. Included only when `type` is `error`.
    - `turns.items.metrics` (object) - Latency metrics for the turn.
      - `turns.items.metrics.e2e_latency_ms` (integer) - The end-to-end latency in milliseconds for the turn.
      - `turns.items.metrics.segmented_latency_ms` (array) - A breakdown of latency by segment.
        - `turns.items.metrics.segmented_latency_ms.items` (object)
          - `turns.items.metrics.segmented_latency_ms.items.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 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.
          - `turns.items.metrics.segmented_latency_ms.items.latency` (number) - The latency in milliseconds for the segment.
### default

The request failed. The response body includes the error details.

- `detail` (string) - Detailed error information.
- `reason` (string) - The reason for the failure.

## Response examples

### 200

```json
{
  "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
          }
        ]
      }
    }
  ]
}
```