# 查询会话中的对话轮次

查询一个已同步会话中供人工预览的消息轮次。

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/{connector_id}/sync-sessions/{session_id}/turns
```

## 调用前准备

先[查询连接器列表](../connectors/list-connectors.md)取得连接器 ID，再[查询同步会话](list-sync-sessions.md)取得会话 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID、连接器 ID 和会话 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID`：Langfuse 连接器 ID。
- `$SESSION_ID`：要查询对话轮次的同步会话 ID。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | Langfuse 连接器 ID。 |
| `session_id` | string | 是 | 同步会话 ID。 |

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/$CONNECTOR_ID/sync-sessions/$SESSION_ID/turns" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`data.messages[].role` 表示 `data.messages` 数组中每一项的 `role` 字段。

成功时返回会话的可读消息预览。此接口不会触发模型调用或记忆提取。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "connector_id": "conn_01",
    "session_id": "session_01",
    "subject_id": "customer_01",
    "message_count": 3,
    "messages": [
      {
        "role": "user",
        "content": "如何查看订单状态？"
      },
      {
        "role": "tool",
        "name": "get_order",
        "content": "订单已发货。"
      },
      {
        "role": "assistant",
        "content": "你的订单已发货。"
      }
    ]
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.connector_id` | string | 关联的 Langfuse 连接器 ID。 |
| `data.session_id` | string | 查询的会话 ID。 |
| `data.subject_id` | string | 会话主体 ID。 |
| `data.message_count` | integer | 返回的预览消息数量。 |
| `data.messages` | object（对象数组） | 面向人工预览的消息。 |
| `data.messages[].role` | string | 消息角色：`user`、`tool` 或 `assistant`。 |
| `data.messages[].content` | string | 可读消息文本。 |
| `data.messages[].name` | string | 工具消息的工具名称；其他角色可能省略。 |

## 错误响应

```json
{
  "code": "ErrParamInvalid",
  "msg": "invalid parameter",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 24 36 28

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParam` 或 `ErrParamInvalid`
  - 连接器或会话 ID 无效，或连接器不是 Langfuse 类型。
  - 先[查询同步会话](list-sync-sessions.md)取得会话 ID，并确认连接器类型。
* - `500`
  - `ErrServer`
  - 服务未能生成消息预览。
  - 稍后重试。
```

## 后续操作

需要选择其他会话时，使用连接器 ID [查询同步会话](list-sync-sessions.md)。需要查看同步进度时，[查询同步状态](get-sync-status.md)。