# 查询同步任务列表

分页查询当前工作区内有权读取的 Langfuse Trace 同步任务，并可按任务名称筛选。

```text
GET https://moi.matrixorigin.cn/newmoi/trace-sync/tasks
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

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

列表只包含调用者有权读取其关联连接器的任务。

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `page` | integer | 否 | 页码；默认 `1`。 |
| `page_size` | integer | 否 | 每页数量；默认 `20`，最大 `200`。超出有效范围时使用默认值。 |
| `keyword` | string | 否 | 按任务名称模糊匹配；首尾空白会被忽略。 |

## 请求示例

```bash
curl --get "https://moi.matrixorigin.cn/newmoi/trace-sync/tasks" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "keyword=production"
```

## 成功响应

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

成功时返回按创建时间倒序排列的任务及分页信息。没有匹配任务时，`tasks` 为空数组。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "tasks": [
      {
        "id": "task_01",
        "connector_id": "conn_01",
        "name": "production-traces",
        "catalog_name": "trace_catalog",
        "database_name": "langfuse_trace_db",
        "table_name": "lf_production_traces",
        "sync_historical": true,
        "user_id_source": "metadata",
        "user_id_metadata_key": "customer_id",
        "poll_interval_sec": 60,
        "session_idle_timeout_sec": 300,
        "session_end_strategy": "idle_timeout",
        "session_end_metadata_key": "session_end",
        "session_end_metadata_value": "ended",
        "sync_status": "steady",
        "last_synced_to": "2026-08-21T08:00:00Z",
        "last_success_at": "2026-08-21T08:00:00Z",
        "auto_extract_enabled": false,
        "created_by": "user_01",
        "created_at": "2026-08-20T08:00:00Z",
        "updated_at": "2026-08-21T08:00:00Z",
        "session_count": 12
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.tasks` | object（对象数组） | 当前页任务。 |
| `data.tasks[].id` | string | 同步任务 ID。 |
| `data.tasks[].connector_id` | string | 关联的连接器 ID。 |
| `data.tasks[].name` | string | 任务名称。 |
| `data.tasks[].catalog_name` | string | 目标 Catalog 名称。 |
| `data.tasks[].database_name` | string | 目标数据库名称。 |
| `data.tasks[].table_name` | string | 目标表名称。 |
| `data.tasks[].sync_historical` | boolean | 是否同步历史数据。 |
| `data.tasks[].start_from` | string | 历史同步起始时间；未设置时省略。 |
| `data.tasks[].user_id_source` | string | 用户标识来源。 |
| `data.tasks[].user_id_metadata_key` | string | metadata 用户标识键。 |
| `data.tasks[].poll_interval_sec` | integer | 拉取间隔秒数。 |
| `data.tasks[].session_idle_timeout_sec` | integer | 会话空闲结束阈值，单位为秒。 |
| `data.tasks[].session_end_strategy` | string | 会话结束判定策略。 |
| `data.tasks[].session_end_metadata_key` | string | 显式结束会话使用的 metadata 键。 |
| `data.tasks[].session_end_metadata_value` | string | 显式结束会话匹配的 metadata 值。 |
| `data.tasks[].sync_status` | string | 同步状态：`not_started`、`catching_up`、`steady` 或 `error`。 |
| `data.tasks[].last_synced_to` | string | 最近同步水位；尚无水位时省略。 |
| `data.tasks[].last_success_at` | string | 最近成功时间；尚未成功时省略。 |
| `data.tasks[].last_error` | string | 最近错误；没有错误时省略。 |
| `data.tasks[].auto_extract_enabled` | boolean | 是否启用自动记忆提取。 |
| `data.tasks[].created_by` | string | 创建者 ID。 |
| `data.tasks[].created_at` | string | 创建时间。 |
| `data.tasks[].updated_at` | string | 更新时间。 |
| `data.tasks[].session_count` | integer | 已发现的同步会话数量。 |
| `data.total` | integer | 匹配任务总数。 |
| `data.page` | integer | 当前页码。 |
| `data.page_size` | integer | 实际每页数量。 |

## 错误响应

```json
{
  "code": "FORBIDDEN",
  "msg": "permission denied",
  "data": null
}
```

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 查询参数格式无效。
  - 检查页码和每页数量是否为整数。
* - `403`
  - `FORBIDDEN`
  - 调用者无权读取连接器资源。
  - 联系管理员检查连接器读取权限。
* - `500`
  - `INTERNAL`
  - 平台未能查询任务或统计会话。
  - 稍后重试。
* - `503`
  - `IAM_UNAVAILABLE`
  - 权限服务暂时不可用。
  - 稍后重试。
```

## 后续操作

从 `data.tasks[].id` 取得目标任务 ID 后[查询同步任务详情](get-sync-task.md)或[更新同步任务](update-sync-task.md)；也可以用 `data.tasks[].connector_id` [查询同步状态](get-sync-status.md)。