# 查询同步状态

查询一个 Langfuse 连接器的同步进度快照，包括最近同步水位、游标和错误信息。

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

## 调用前准备

先[查询连接器列表](../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。 |

## 请求示例

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

## 成功响应

成功时返回连接器的同步快照。尚未开始同步时，最近同步时间可以为 `null`，游标和错误信息可以为空。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "connector_id": "conn_01",
    "sync_status": "steady",
    "last_synced_to": "2026-08-21T08:00:00Z",
    "last_cursor": "cursor_01",
    "last_success_at": "2026-08-21T08:00:00Z",
    "last_error": ""
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.connector_id` | string | 查询的连接器 ID。 |
| `data.sync_status` | string | 同步状态：`not_started`、`catching_up`、`steady` 或 `error`。 |
| `data.last_synced_to` | string 或 null | 最近一次已同步数据的高水位时间，采用 RFC 3339 时间格式。 |
| `data.last_cursor` | string | 当前同步游标。 |
| `data.last_success_at` | string 或 null | 最近一次成功同步的时间。 |
| `data.last_error` | string | 最近一次同步错误；没有错误时为空字符串。 |

## 错误响应

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 连接器不是 Langfuse 类型，或参数无效。
  - 使用 Langfuse 连接器 ID 后重试。
* - `500`
  - `ErrServer`
  - 服务未能读取同步状态。
  - 稍后重试。
```

## 后续操作

需要修改同步配置时，先使用连接器 ID [按连接器查询同步任务](list-connector-sync-tasks.md)，再[更新同步任务](update-sync-task.md)。需要浏览已发现会话时，使用同一连接器 ID [查询同步会话](list-sync-sessions.md)。