# 列出运行步骤 (/docs/api/native/automation/listRunTasks)





分页读取步骤账本；include=planned 附带尚未执行的顶层步骤，group_by=reference 按步骤引用聚合次数、状态和耗时。

`GET /automation/v1/runs/{id}/tasks`

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

## 请求字段 [#请求字段]

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| path: id | `string` | 必填；运行 ID（run_）。 |
| query: limit | `integer` | 可选；运行台账每页条数，整数 1–200，默认 50；其它集合上限为 100。 minimum: 1；maximum: 200 |
| query: cursor | `string` | 可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。 |
| query: include | `"planned"` | 可选；仅支持 planned，附带尚未执行的顶层步骤；省略只读已有步骤。 |
| query: group_by | `"reference"` | 可选；仅支持 reference，按步骤引用聚合循环执行；省略返回逐次步骤。 |

## 示例 [#示例]

[SDK 安装与示例环境](/docs/api/native/automation)

先设置以下环境变量，使用你自己的资源：

| 变量 | 来源 |
| --- | --- |
| RUN_ID | [运行 id；暂停和恢复仅工作流；取消需非终态运行](/docs/api/native/automation/createRun) |

```bash
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
```

```typescript
import { createAutomationClient } from '@deepractice-ai/praxis-sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.tasks.list({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data | `object` / `object[]` | 必填 / 必有；本页的工作流步骤记录；group_by=reference 时为按 reference 聚合的 TaskGroup 行，按执行顺序排列。 |
| data[]（分支1).id | `string` | 必填 / 必有；步骤执行记录的标识，按不透明字符串处理。 |
| data[]（分支1).run_id | `string` | 必填 / 必有；所属运行 ID。 |
| data[]（分支1).reference | `string` | 必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。 |
| data[]（分支1).name | `string` | 必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。 |
| data[]（分支1).kind | `"run"` / `"call"` / `"wait"` / `"set"` / `"for"` / `"fork"` / `"try"` / `"switch"` / `"emit"` / `"raise"` / `"listen"` / `"do"` | 必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。 |
| data[]（分支1).iteration | `number[]` | 必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。 |
| data[]（分支1).attempt | `number` | 必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。 |
| data[]（分支1).status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。 |
| data[]（分支1).skipped | `boolean` | 必填 / 必有；true 表示该步骤被跳过而没有实际执行。 |
| data[]（分支1).started_at | `null` / `string` | 必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。 |
| data[]（分支1).ended_at | `null` / `string` | 必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。 |
| data[]（分支1).duration_ms | `null` / `number` | 必填 / 必有；执行耗时毫秒数；未结束为 null。 |
| data[]（分支1).input | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| data[]（分支1).input（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| data[]（分支1).input（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| data[]（分支1).input_truncated | `boolean` | 必填 / 必有；true 表示 input 超过 32 KB 已被截断。 |
| data[]（分支1).output | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| data[]（分支1).output（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| data[]（分支1).output（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| data[]（分支1).output_truncated | `boolean` | 必填 / 必有；输出超过内联限制而被省略时为 true。 |
| data[]（分支1).error | `null` / `object` | 必填 / 必有；步骤失败时的错误详情；未失败为 null。 |
| data[]（分支1).error（分支2).type | `string` | 必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。 |
| data[]（分支1).error（分支2).code | `null` / `string` | 必填 / 必有；稳定错误码，可按码分支处理；没有为 null。 |
| data[]（分支1).error（分支2).title | `string` | 必填 / 必有；错误的简短标题。 |
| data[]（分支1).error（分支2).detail | `null` / `string` | 必填 / 必有；错误的详细说明；没有为 null。 |
| data[]（分支1).error（分支2).source | `null` / `object` | 必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。 |
| data[]（分支1).error（分支2).source（分支2).kind | `"call"` / `"task"` | 必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。 |
| data[]（分支1).error（分支2).source（分支2).reference | `string` | 可选；task 类型时：出错步骤的 JSON Pointer。 |
| data[]（分支1).error（分支2).source（分支2).seq | `number` | 可选；call 类型时：出错调用的序号（与 Call.seq 对应）。 |
| data[]（分支1).error（分支2).source（分支2).action | `object` | 可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。 |
| data[]（分支1).error（分支2).source（分支2).action.name | `string` | 必填 / 必有；动作全名 ns/name。 |
| data[]（分支1).error（分支2).source（分支2).action.revision | `string` | 必填 / 必有；执行的动作修订 ID（actr_ 前缀）。 |
| data[]（分支1).error（分支2).request_id | `string` / `null` | 可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。 |
| data[]（分支1).error（分支2).errors | `object[]` | 可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。 |
| data[]（分支1).error（分支2).errors[].pointer | `string` | 必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。 |
| data[]（分支1).error（分支2).errors[].detail | `string` | 必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。 |
| data[]（分支1).error（分支2).errors[].hint | `string` | 可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。 |
| data[]（分支1).error（分支2).errors[].line | `integer` | 可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| data[]（分支1).error（分支2).errors[].column | `integer` | 可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| data[]（分支1).error（分支2).status | `number` | 可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。 |
| data[]（分支1).action | `null` / `object` | 必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。 |
| data[]（分支1).action（分支2).name | `string` | 必填 / 必有；动作全名 ns/name。 |
| data[]（分支1).action（分支2).revision | `string` | 必填 / 必有；执行的动作修订 ID（actr_ 前缀）。 |
| data[]（分支1).child_run | `null` / `object` | 必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。 |
| data[]（分支1).child_run（分支2).id | `string` | 必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。 |
| data[]（分支1).child_run（分支2).number | `null` / `number` | 必填 / 必有；子运行在其定义内的序号；临时运行为 null。 |
| data[]（分支1).child_run（分支2).status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。 |
| data[]（分支1).child_run（分支2).resolved_version | `null` / `string` | 必填 / 必有；子运行解析到的精确版本号；临时运行为 null。 |
| data[]（分支2).reference | `string` | 必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。 |
| data[]（分支2).name | `string` | 必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。 |
| data[]（分支2).count | `number` | 必填 / 必有；该 reference 下合并的执行记录条数（循环的迭代数）。 |
| data[]（分支2).status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。 |
| data[]（分支2).duration_ms | `null` / `number` | 必填 / 必有；执行耗时毫秒数；未结束为 null。 |
| next_cursor | `null` / `string` | 必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。 |

### 实测响应 [#实测响应]

HTTP 200

```json
{
  "data": [],
  "next_cursor": null
}
```

## 错误码 [#错误码]

| HTTP | 错误码与说明 |
| --- | --- |
| 400 | INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 |
| 404 | RUN_NOT_FOUND：运行不存在或当前租户不可见。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

[鉴权错误与通用错误](/docs/api/errors) · 排查时保留响应头 `X-Request-Id`。