# 查询对话轮次信息 (/zh-CN/api-reference/api-ref/conversational-ai/turns) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 在与智能体会话结束后，调用该接口分页查询本次会话的对话轮次信息，包含每个对话轮次的开始信息、结束信息、性能指标。 - OpenAPI: /openapi/conversational-ai/rest-api.zh-CN.yaml - Operation ID: get-turns - Method: GET - Path: /v2/projects/{appid}/agents/{agentId}/turns - Endpoint: https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/turns ## Servers - https://api.agora.io/cn/api/conversational-ai-agent :::warning[注意] 自 v2.7 起，该接口从单次返回全部对话轮次改为分页返回。默认请求第 1 页，默认每页返回 50 条对话轮次数据。 仅支持查询 7 天内的会话。 ::: ## Authorization This endpoint requires authentication. - `Basic Auth` - `Agora Token` ## Parameters - `Authorization` (header, required, string) - 发送 HTTP 请求时，你可以从以下鉴权方式中任选其一： 1. **使用 Token 认证（推荐）**：参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-token-认证)生成 Token 并填入 `Authorization` Header。传参示例：`Authorization: agora token="007abcxxxxxxx123"`。 2. **使用 Basic Auth**：参考[实现 HTTP 鉴权](/zh-CN/ai/build/http-basic-auth#使用-http-基本认证)生成 Base64 编码的 `Authorization` 字段。传参示例：`Authorization: Basic NDI1OTQ3N2I4MzYy...YwZjA=`。 - Example: `agora token="007abcxxxxxxx123"` - `appid` (path, required, string) - 你的项目使用的 [App ID](/zh-CN/ai/get-started/enable-service#%E8%8E%B7%E5%8F%96-app-id)。 - `agentId` (path, required, string) - 智能体实例 ID，即智能体的唯一标识。调用 [POST 创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join) 成功后在响应包体中获取。 - `page_index` (query, optional, integer) - 页码。从 `1` 开始。默认值为 `1`。 - Default: `1` - `page_size` (query, optional, integer) - 每页返回的对话轮次数量。默认值为 `50`，取值范围为 [10,200]。 - Default: `50` ## Request body No request body. ## Responses ### 200 - 若返回的状态码为 `200` 则表示请求成功。响应包体中包含本次请求的结果。 - 若返回的状态码不为 `200` 则表示请求失败。响应包体中包含错误的类别和描述，你可以参考[响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)了解可能的原因。 - `agent_id` (string) - 智能体唯一标识。 - `name` (string) - 智能体名称。 - `channel` (string) - 对话频道名称。 - `total_turn_count` (integer) - 当前会话中的对话轮次总数。 - `pagination` (object) - 分页信息。 - `pagination.page_index` (integer) - 当前页码，从 1 开始。 - `pagination.total_pages` (integer) - 总页数。 - `pagination.is_last_page` (boolean) - 当前页是否为最后一页。 - `turns` (array) - 对话轮次列表。 - `turns.items` (object) - `turns.items.agent_id` (string) - 智能体唯一标识。 - `turns.items.channel` (string) - 对话频道名称。 - `turns.items.turn_id` (integer) - 对话轮次 ID，从 1 开始递增。 - `turns.items.start` (object) - 轮次开始信息。 - `turns.items.start.start_at` (integer) - 开始时间戳，毫秒级 UTC 时间。 - `turns.items.start.type` (string) - 开始类型： - `voice_input`：因用户语音输入而开始。 - `greeting`：因智能体播报问候语而开始。 - `silence_timeout`：因智能体静音超时而开始。 - `api_speak`：因调用[播报自定义信息](/zh-CN/api-reference/api-ref/conversational-ai/speak)接口播报信息而开始。 - `api_think`：因 API 调用思考而开始。 - `turns.items.start.metadata` (object) - 开始附加元数据，根据 `type` 字段的不同，包含不同的字段。 - `turns.items.start.metadata.transport` (string) - 传输协议： - `http`：HTTP 协议。 - `rtm`：通过 RTM Presence 通道传输。 - `turns.items.start.metadata.action` (string) - - `speak`：播报静默提示内容。 - `think`：将静默提示内容追加在上下文的最后，并传递给 LLM。 - `turns.items.start.metadata.greeting_nth` (integer) - 问候语播放次数。 - `turns.items.start.metadata.speech_duration_ms` (integer) - 语音持续时长(ms)。 - `turns.items.start.metadata.interrupt_duration_ms` (integer) - 智能体空闲或倾听时的人声持续阈值 (ms)。 - `turns.items.end` (object) - 轮次结束信息。 - `turns.items.end.end_at` (integer) - 结束时间戳，毫秒级 UTC 时间。 - `turns.items.end.type` (string) - 轮次结束类型： - `ok`：正常结束。 - `interrupted`：被中断。 - `ignored`：被忽略。 - `error`：执行错误。 - `turns.items.end.metadata` (object) - 结束附加元数据，根据 `type` 字段的不同，包含不同的字段。 - `turns.items.end.metadata.reason` (string) - 错误类型，可能包含以下值： - `LLM_REQUEST_ERR`：LLM 请求错误。 - `TTS_REQUEST_ERR`：TTS 请求错误。 - `INTERNAL_ERR`：内部错误。 - `turns.items.end.metadata.details` (string) - 错误详情。 - `turns.items.end.metadata.caused_by` (string) - 轮次中断原因： - `start_of_speech`：新一条语音请求开始。 - `api_speak`：因调用[播报自定义信息](/zh-CN/api-reference/api-ref/conversational-ai/speak)接口播报信息而中断。 - `api_think`：因 API 调用思考而中断。 - `api_interrupt`：因调用[打断智能体](/zh-CN/api-reference/api-ref/conversational-ai/interrupt)接口而中断。 - `api_leave`：因调用[停止对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/leave)接口离开频道而中断。 - `user_no_longer_present`：因智能体检测不到可订阅用户而中断。 - `turns.items.end.metadata.playback_duration_ms` (integer) - 语音播放时长(ms)。 - `turns.items.end.metadata.intended_playback_duration_ms` (integer) - 当前轮次中计划播放的 PCM 音频总时长（ms），包含尚未播放完的排队音频。 - `turns.items.end.metadata.transport` (string) - 传输协议（`caused_by` 为 `api_speak`、`api_interrupt` 或 `api_think` 时返回）： - `http`：HTTP 协议。 - `rtm`：通过 RTM Presence 通道传输。 - `turns.items.metrics` (object) - 对话轮次性能指标详情。 - `turns.items.metrics.e2e_latency_ms` (integer) - 端到端总延迟 (ms)。 - `turns.items.metrics.segmented_latency_ms` (array) - 分段延迟指标详情列表。 - `turns.items.metrics.segmented_latency_ms.items` (object) - `turns.items.metrics.segmented_latency_ms.items.name` (string) - 延迟模块名称，根据[创建对话式智能体](/zh-CN/api-reference/api-ref/conversational-ai/join)时设置的 LLM 输入模态的不同，返回不同的延迟模块。 - `turns.items.metrics.segmented_latency_ms.items.latency` (integer) - 延迟时间 (ms)。 ## 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", "playback_duration_ms": 1200, "intended_playback_duration_ms": 2400 } }, "metrics": { "e2e_latency_ms": 337, "segmented_latency_ms": [ { "name": "tts_ttfb", "latency": 337 } ] } } ] } ```