> ## Documentation Index > Fetch the complete documentation index at: https://docs.coze.cn/llms.txt > Use this file to discover all available pages before exploring further. 查看对话的详细信息。 在非流式会话场景中，调用[发起对话](https://docs.coze.cn/developer_guides/chat_v3)接口后，可以先轮询此 API 确认本轮对话已结束（status=completed），再调用接口[查看对话消息详情](https://docs.coze.cn/developer_guides/list_chat_messages)查看本轮对话的模型回复。 :::tip 说明 * 仅在对话开启了保存历史记录（auto_save_history=true）后，可通过此接口查看对话的详细信息。 * 建议一个对话每秒轮询一次。 ::: ## 基础信息 {#基础信息} | | | \ |**请求方式** |GET | |---|---| | | | \ |**请求地址** |```Plain Text |\ | |https://api.coze.cn/v3/chat/retrieve |\ | |``` |\ | | | | | | \ |**权限** |`getChat` |\ | |确保调用该接口使用的个人令牌开通了 `getChat` 权限，详细信息参考[鉴权方式](https://docs.coze.cn/developer_guides/authentication)。 | | | | \ |**接口说明** |查看对话的详细信息。 | ## 请求参数 {#请求参数} ### Header {#Header} | | | | \ |**参数** |**取值** |**说明** | |---|---|---| | | | | \ |Authorization |Bearer *$Access_Token* |用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考[准备工作](https://docs.coze.cn/developer_guides/preparation)。 | | | | | \ |Content-Type |application/json |解释请求正文的方式。 | ### Query {#Query} | | | | | | \ |**参数** |**类型** |**是否必选** |**示例** |**说明** | |---|---|---|---|---| | | | | | | \ |conversation_id |String |必选 |738137187639794**** |Conversation ID，即会话的唯一标识。可以在[发起对话](https://docs.coze.cn/developer_guides/chat_v3)接口 Response 中查看 conversation_id 字段。 | | | | | | | \ |chat_id |String |必选 |738136585609548**** |Chat ID，即对话的唯一标识。可以在[发起对话](https://docs.coze.cn/developer_guides/chat_v3)接口 Response 中查看 id 字段，如果是流式响应，则在 Response 的 chat 事件中查看 id 字段。 | ## 返回参数 {#返回参数} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |data |Object of [ChatV3ChatDetail](#chatv3chatdetail) |\ |本次对话的基本信息。 | | | | | | \ |detail |Object of [ResponseDetail](#responsedetail) |20241210152726467C48D89D6DB2**** |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 `logid`及错误码联系扣子团队获取帮助。 | | | | | | \ |code |Long |0 |调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。 | | | | | | \ |msg |String |"" |状态信息。API 调用失败时可通过此字段查看详细错误信息。 |\ | | | |状态码为 0 时，msg 默认为空。 | ### ChatV3ChatDetail {#chatv3chatdetail} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |id |String |738137187639794**** |对话 ID，即对话的唯一标识。 | | | | | | \ |conversation_id |String |738136585609548**** |会话 ID，即会话的唯一标识。 | | | | | | \ |bot_id |String |737946218936519**** |该会话所属的智能体的 ID。 | | | | | | \ |status |String |completed |对话的运行状态。取值为： |\ | | | | |\ | | | |* created：对话已创建。 |\ | | | |* in_progress：智能体正在处理中。 |\ | | | |* completed：智能体已完成处理，本次对话结束。 |\ | | | |* failed：对话失败。 |\ | | | |* requires_action：对话中断，需要进一步处理。 |\ | | | |* canceled：对话已取消。 | | | | | | \ |created_at |Integer |1718609571 |对话创建的时间。格式为 10 位的 Unixtime 时间戳，单位为秒。 | | | | | | \ |completed_at |Integer |1718609575 |对话结束的时间。格式为 10 位的 Unixtime 时间戳，单位为秒。 | | | | | | \ |failed_at |Integer |1718609571 |对话失败的时间。格式为 10 位的 Unixtime 时间戳，单位为秒。 | | | | | | \ |meta_data |JSON Map |{"customKey1":"customValue1","customKey2":"customValue2"} |发起对话时的附加消息，用于传入使用方的自定义数据，[查看对话详情](https://docs.coze.cn/developer_guides/retrieve_chat)时也会返回此附加消息。 |\ | | | |自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。 | | | | | | \ |last_error |Object of [LastError](#lasterror) |\ |对话运行异常时，此字段中返回详细的错误信息，包括： |\ | | | | |\ | | | |* Code：错误码。Integer 类型。0 表示成功，其他值表示失败。 |\ | | | |* Msg：错误信息。String 类型。 | | | | | | \ |section_id |String |737946218936519**** |上下文片段 ID。每次调用[清除上下文](https://docs.coze.cn/developer_guides/clear_conversation_context) API 都会生成一个新的 section_id。 | | | | | | \ |required_action |Object of [RequiredAction](#requiredaction) |{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"738137187639794****","type":"function","function":{"name":"get_weather","arguments":"{\"city\":\"Beijing\"}"}}]}} |当对话状态为 `requires_action` 时，此字段包含需要进一步处理的信息详情，用于继续对话。 | | | | | | \ |usage |Object of [Usage](#usage) | |预留字段，无需关注，具体消耗的 Token 请查看火山账单。 | ### LastError {#lasterror} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |msg |String |详见响应示例 |状态信息。API 调用失败时可通过此字段查看详细错误信息。 | | | | | | \ |code |Integer |0 |状态码。 |\ | | | |0 代表调用成功。 | ### RequiredAction {#requiredaction} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |type |String |submit_tool_outputs |额外操作的类型，枚举值： |\ | | | |`submit_tool_outputs`：需要提交工具输出以继续对话。 | | | | | | \ |submit_tool_outputs |Object of [SubmitToolOutputs](#submittooloutputs) |{"tool_calls":[{"id":"738137187639794****","type":"function","function":{"name":"get_weather","arguments":"{\"city\":\"Beijing\"}"}}]} |当对话状态为 `requires_action`时，此字段包含需要提交的工具输出信息，用于继续对话。通常包含一个工具调用列表，每个工具调用包含工具类型和参数。 | ### SubmitToolOutputs {#submittooloutputs} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |tool_calls |Array of [InterruptPlugin](#interruptplugin) |[{"id":"738137187639794****","type":"function","function":{"name":"get_weather","arguments":"{\"city\":\"Beijing\"}"}}] |当对话状态为 `requires_action` 时，此字段包含需要提交的工具调用列表，每个工具调用包含工具类型和参数。 | ### InterruptPlugin {#interruptplugin} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |id |String |738137187639794**** |上报运行结果的 ID。 | | | | | | \ |type |String |function |工具类型，枚举值包括： |\ | | | | |\ | | | |* function：待执行的方法，通常是端插件。触发端插件时会返回此枚举值。 |\ | | | |* reply_message：待回复的选项。触发工作流问答节点时会返回此枚举值。 | | | | | | \ |function |Object of [InterruptFunction](#interruptfunction) |{"name":"get_weather","arguments":"{\"city\":\"Beijing\"}"} |当对话状态为 `requires_action`时，此字段表示需要调用的工具或函数的定义，包含函数名称和参数。通常用于指定工具的具体执行方法。 | ### InterruptFunction {#interruptfunction} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |name |String |get_weather |当对话状态为 `requires_action` 时，此字段表示需要调用的工具或函数的名称，用于继续对话。通常与 `arguments`字段配合使用，指定工具的具体执行方法。 | | | | | | \ |arguments |String |{"city":"Beijing"} |当对话状态为 `requires_action`时，此字段表示需要调用的工具或函数的参数，通常为 JSON 格式的字符串，用于指定工具的具体执行参数。 | ### Usage {#usage} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |input_count |Integer |50 |输入内容所消耗的 Token 数，包含对话上下文、系统提示词、用户当前输入等所有输入类的 Token 消耗。 | | | | | | \ |token_count |Integer |150 |本次 API 调用消耗的 Token 总量，包括输入和输出两部分的消耗。 | | | | | | \ |output_count |Integer |100 |大模型输出的内容所消耗的 Token 数。 | ### ResponseDetail {#responsedetail} | | | | | \ |**参数** |**类型** |**示例** |**说明** | |---|---|---|---| | | | | | \ |logid |String |20241210152726467C48D89D6DB2**** |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此 logid 及错误码联系扣子团队获取帮助。详细说明可参考[获取帮助和技术支持](https://docs.coze.cn/guides/help_and_support)。 | ## 示例 {#示例} ### 请求示例 {#请求示例} ```JSON curl --location --request GET 'https://api.coze.cn/v3/chat/retrieve?conversation_id=738137187639794****&chat_id=738136585609548****' \ --header 'Authorization: Bearer *$Access_Token*' \ --header 'Content-Type: application/json' ``` ### 返回示例 {#返回示例} :::: tabs @tab 状态正常的对话 ```JSON { "code": 0, "data": { "bot_id": "737946218936519****", "completed_at": 1718609575, "conversation_id": "738136585609548****", "created_at": 1718609571, "id": "738137187639794****", "status": "completed", "usage": { "input_count": 242, "output_count": 56, "token_count": 298 } }, "msg": "" } ``` @tab 需要使用方额外处理的对话 ```JSON { "code": 0, "data": { "bot_id": "737282596785517****", "completed_at": 1717513285, "conversation_id": "737666232053956****", "created_at": 1717513283, // 在 chat 事件里，data 字段中的 id 为 Chat ID，即会话 ID。 "id": "737666232053959****", "required_action": { "submit_tool_outputs": { "tool_calls": [ { "function": { "arguments": "{\"location\":\"南京\",\"type\":0}", "name": "local_data_assistant" }, "id": "BUJJF0dAQ0NAEBVeQkVKEV5HFURFXhFCEhFeFxdHShcS****", "type": "function" } ] }, "type": "submit_tool_outputs" }, "status": "requires_action" }, "msg": "" } ``` :::: ## 错误码 {#错误码} 该接口有两处错误需要判断。一个位于回包的`.code`，对应该接口本身的错误；另一个位于回包的`.last_error.code`，对应/v3/chat的错误。 如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考[错误码](https://docs.coze.cn/developer_guides/coze_error_codes)文档查看对应的解决方法。