# 查询同步会话

分页列出一个 Langfuse 连接器已经发现的同步会话。

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

## 调用前准备

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

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID`：Langfuse 连接器 ID。

该接口只适用于可访问的 Langfuse 连接器。

## 路径参数

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

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `page` | integer | 否 | 页码。默认值为 `1`。 |
| `page_size` | integer | 否 | 每页数量。默认值为 `20`。 |
| `sync_status` | string | 否 | 会话同步状态：`open` 或 `closed`。 |
| `memory_status` | string | 否 | 记忆处理状态：`not_ready`、`pending`、`processing`、`done`、`error` 或 `workflow_failed`。 |
| `keyword` | string | 否 | 按 session ID 或 subject ID 模糊筛选。 |

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/$CONNECTOR_ID/sync-sessions?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

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

成功时返回当前页会话和匹配总数。根据总数与请求的每页数量计算最后一页，再依次增加 `page` 读取后续结果。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "sessions": [
      {
        "connector_id": "conn_01",
        "session_id": "session_01",
        "subject_id": "customer_01",
        "first_observation_time": "2026-08-21T07:00:00Z",
        "last_observation_time": "2026-08-21T08:00:00Z",
        "trace_count": 2,
        "observation_count": 6,
        "sync_status": "closed",
        "memory_status": "done",
        "turn_count": 4,
        "first_user_snippet": "如何查看订单状态？"
      }
    ],
    "total": 1
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.sessions` | object（对象数组） | 当前页的同步会话。 |
| `data.sessions[].connector_id` | string | 关联的连接器 ID。 |
| `data.sessions[].session_id` | string | 会话 ID。 |
| `data.sessions[].subject_id` | string | 会话主体 ID。 |
| `data.sessions[].first_observation_time` | string | 首次 observation 的时间，采用 RFC 3339 时间格式。 |
| `data.sessions[].last_observation_time` | string | 最近 observation 的时间，采用 RFC 3339 时间格式。 |
| `data.sessions[].trace_count` | integer | 会话中的 Trace 数量。 |
| `data.sessions[].observation_count` | integer | 会话中的 observation 数量。 |
| `data.sessions[].turn_count` | integer | 会话中的可预览消息数量。 |
| `data.sessions[].sync_status` | string | 会话同步状态。 |
| `data.sessions[].memory_status` | string | 记忆处理状态。 |
| `data.sessions[].memory_processed_at` | string | 记忆处理完成时间；未处理时可能省略。 |
| `data.sessions[].memory_error` | string | 最近的记忆处理错误；没有错误时可能省略。 |
| `data.sessions[].last_error` | string | 最近的同步错误；没有错误时可能省略。 |
| `data.sessions[].first_user_snippet` | string | 第一条用户消息的预览文本。 |
| `data.total` | integer | 匹配条件的会话总数。 |

## 错误响应

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParam` 或 `ErrParamInvalid`
  - 查询参数格式、状态筛选值或连接器类型无效。
  - 使用允许的筛选值并确认连接器为 Langfuse 类型。
* - `500`
  - `ErrServer`
  - 服务未能读取会话。
  - 稍后重试。
```

## 后续操作

记录 `data.sessions[].session_id`。需要预览会话消息时，带着连接器 ID 和会话 ID [查询会话中的对话轮次](list-session-turns.md)；需要查看整体进度时，[查询同步状态](get-sync-status.md)。