运行记录
查询文档运行的历史记录。
源码: apps/backend/src/routes/runs.ts
GET /runs
查询项目下的运行记录列表。
认证方式
JWT Token（仅支持 JWT，combinedAuth）
请求参数
Query 参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
projectId | string | 是 | - | 项目 UUID |
documentId | string | 否 | - | 文档 UUID，按文档筛选 |
deploymentId | string | 否 | - | 部署 UUID，按部署筛选 |
sourceType | string | 否 | - | 来源类型：editor、api_key、schedule |
page | number | 否 | 1 | 页码（最小 1） |
pageSize | number | 否 | 20 | 每页数量（最大 100） |
响应格式
状态码: 200
{
"runs": [
{
"id": "uuid",
"owner_user_id": "uuid",
"project_id": "uuid",
"document_id": "uuid",
"deployment_id": "uuid",
"source_type": "editor",
"triggered_by_user_id": "uuid",
"api_key_id": null,
"status": "success",
"data": {
"inputs": {},
"globalCtx": [...],
"duration": 1234,
"completedBlocks": 3,
"timedOut": false
},
"created_at": "2026-03-07T12:00:00.000Z",
"updated_at": "2026-03-07T12:00:01.234Z",
"deleted_at": null,
"api_key": {
"team": { "name": "我的团队" }
},
"deployment": {
"version_major": 1,
"version_minor": 2
}
}
],
"total": 100,
"page": 1,
"pageSize": 20
}| 字段 | 类型 | 说明 |
|---|---|---|
runs | RunRecord[] | 运行记录数组（含关联的 api_key 和 deployment 信息） |
total | number | 总记录数 |
page | number | 当前页码 |
pageSize | number | 每页数量 |
记录按 created_at 降序排列。
请求示例
# 查询项目所有运行记录
curl -H "Authorization: Bearer YOUR_JWT" \
"https://block2-api.wainao.chat/runs?projectId=PROJECT_UUID"
# 按来源类型筛选
curl -H "Authorization: Bearer YOUR_JWT" \
"https://block2-api.wainao.chat/runs?projectId=PROJECT_UUID&sourceType=api_key&page=1&pageSize=10"错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 400 | projectId is required | 缺少 projectId |
| 400 | Invalid sourceType: xxx | sourceType 无效 |
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证 |
| 403 | 无权访问该项目 | 非项目所有者且非团队成员 |
| 404 | 项目不存在 | 项目不存在或已删除 |
GET /runs/:runId
获取单条运行记录详情。
认证方式
JWT Token（仅支持 JWT，combinedAuth）
请求参数
Path 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
runId | string | 是 | 运行记录 UUID |
响应格式
状态码: 200
返回完整的运行记录对象（含关联的 api_key 和 deployment 信息），结构与列表接口中的单条记录一致。
{
"id": "uuid",
"owner_user_id": "uuid",
"project_id": "uuid",
"document_id": "uuid",
"deployment_id": "uuid",
"source_type": "api_key",
"triggered_by_user_id": "uuid",
"api_key_id": "uuid",
"status": "success",
"data": {
"inputs": { "text": "hello" },
"globalCtx": [...],
"duration": 2345,
"completedBlocks": 5,
"timedOut": false
},
"created_at": "2026-03-07T12:00:00.000Z",
"api_key": { "team": { "name": "我的团队" } },
"deployment": { "version_major": 1, "version_minor": 0 }
}错误码
| 状态码 | 错误 | 说明 |
|---|---|---|
| 403 | 仅支持 JWT 认证 | 使用了非 JWT 认证 |
| 403 | 无权访问该运行记录 | 非项目所有者且非团队成员 |
| 404 | 运行记录不存在 | 记录不存在或已删除 |
| 404 | 项目不存在 | 记录关联的项目不存在 |
补充端点
本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。
POST /runs
创建一次运行记录或提交新的运行请求。
认证：JWT Bearer Token 或 API Key（combinedAuth）。 请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。
响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
POST /runs/:runId/cancel
取消正在执行的运行。
认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数
| 参数 | 说明 |
|---|---|
runId | 运行记录 ID |
请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。
响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
GET /runs/:runId/events
读取指定运行的事件流历史。
认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数
| 参数 | 说明 |
|---|---|
runId | 运行记录 ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
GET /runs/:runId/globalctx-events
读取指定运行的 global context 事件历史。
认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数
| 参数 | 说明 |
|---|---|
runId | 运行记录 ID |
请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。
响应：成功时返回目标资源详情、状态或配置对象。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。
POST /runs/:runId/resume
恢复被 Ask、人工确认或中断流程暂停的运行。
认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数
| 参数 | 说明 |
|---|---|
runId | 运行记录 ID |
请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。
响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。
常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。