# 读取运行 (/docs/api/native/automation/getRun)





读取运行详情，可用 expand 一次带回调用、步骤、步骤聚合、日志或源码；传 wait（秒，0–60）可挂起请求直到运行到达终态或超时，不必轮询；展开页最多 200 条，后续通过各账本端点的游标读取。 工作流 raise 错误保留完整 type URI、status、title、detail；只有平台内部异常归为 runtime。

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

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

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

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| path: id | `string` | 必填；运行 ID（run_）。 |
| query: expand | `"calls"` / `"tasks"` / `"task_groups"` / `"logs"` / `"source"[]` | 可选；逗号分隔且不能重复：calls、tasks、task_groups、logs、source，这是全部合法取值（output 不是展开项，运行输出在 output 字段里）；省略不展开，展开页最多 200 条。无效取值返回 INVALID_PARAMS 并列出合法取值。 minItems: 1 |
| query: wait | `integer` | 可选；等待运行到达终态的秒数，0–60 的整数，默认 0（立即返回）。超时后运行仍未结束则返回当前运行（状态码仍为 200），请检查 status；超过 60 或不是整数返回 INVALID_PARAMS。含义与 runs.create 的 wait 相同。 minimum: 0；maximum: 60 |

## 示例 [#示例]

[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}" \
  -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.retrieve({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | `string` | 必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。 |
| kind | `"script"` / `"workflow"` | 必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。 |
| number | `null` / `number` | 必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。 |
| definition | `null` / `object` | 必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。 |
| definition（分支2).namespace | `string` | 必填 / 必有；脚本或工作流的命名空间。 |
| definition（分支2).name | `string` | 必填 / 必有；脚本或工作流的名字。 |
| target | `null` / `string` | 必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。 |
| resolved_version | `null` / `string` | 必填 / 必有；target 解析到的精确版本号；临时运行为 null。 |
| source_digest | `null` / `string` | 必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。 |
| language | `"ts"` / `"yaml"` | 必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。 |
| status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。 |
| progress | `null` / `object` | 必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。 |
| progress（分支2).label | `string` | 必填 / 必有；进度说明文字，例如当前阶段。 |
| progress（分支2).current | `null` / `number` | 必填 / 必有；已完成的数量；未报告为 null。 |
| progress（分支2).total | `null` / `number` | 必填 / 必有；总量；未知为 null。 |
| progress（分支2).updated_at | `string` | 必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。 |
| current_wait | `null` / `object` | 必填 / 必有；运行当前未完成的等待点；不在等待为 null。 |
| current_wait（分支2).id | `string` | 必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。 |
| current_wait（分支2).run_id | `string` | 必填 / 必有；所属运行 ID（run_ 前缀）。 |
| current_wait（分支2).kind | `"event"` / `"timer"` / `"child"` | 必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。 |
| current_wait（分支2).state | `"cancelled"` / `"open"` / `"resolved"` / `"expired"` | 必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。 |
| current_wait（分支2).task | `null` / `object` | 必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。 |
| current_wait（分支2).task（分支2).reference | `string` | 必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。 |
| current_wait（分支2).task（分支2).name | `string` | 必填 / 必有；步骤名，即工作流 YAML 中的键。 |
| current_wait（分支2).resume_at | `null` / `string` | 必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。 |
| current_wait（分支2).event_type | `null` / `string` | 必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。 |
| current_wait（分支2).child_run_id | `null` / `string` | 必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。 |
| current_wait（分支2).created_at | `string` | 必填 / 必有；等待点创建时间（RFC 3339 UTC）。 |
| current_wait（分支2).expires_at | `null` / `string` | 必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。 |
| current_wait（分支2).resolved_at | `null` / `string` | 必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。 |
| counters | `object` | 必填 / 必有；运行的累计计数。 不接受额外字段。 |
| counters.calls | `number` | 必填 / 必有；脚本发出的调用总数。 |
| counters.action_calls | `number` | 必填 / 必有；其中调用动作的次数。 |
| counters.child_runs | `number` | 必填 / 必有；启动的子运行数。 |
| counters.tasks_completed | `number` | 必填 / 必有；工作流已完成的步骤数。 |
| counters.tasks_total | `null` / `number` | 必填 / 必有；工作流顶层步骤总数；脚本运行为 null。 |
| input | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| input（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| input（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| output | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| output（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| output（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| error | `null` / `object` | 必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。 |
| error（分支2).type | `string` | 必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。 |
| error（分支2).code | `null` / `string` | 必填 / 必有；稳定错误码，可按码分支处理；没有为 null。 |
| error（分支2).title | `string` | 必填 / 必有；错误的简短标题。 |
| error（分支2).detail | `null` / `string` | 必填 / 必有；错误的详细说明；没有为 null。 |
| error（分支2).source | `null` / `object` | 必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。 |
| error（分支2).source（分支2).kind | `"call"` / `"task"` | 必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。 |
| error（分支2).source（分支2).reference | `string` | 可选；task 类型时：出错步骤的 JSON Pointer。 |
| error（分支2).source（分支2).seq | `number` | 可选；call 类型时：出错调用的序号（与 Call.seq 对应）。 |
| error（分支2).source（分支2).action | `object` | 可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。 |
| error（分支2).source（分支2).action.name | `string` | 必填 / 必有；动作全名 ns/name。 |
| error（分支2).source（分支2).action.revision | `string` | 必填 / 必有；执行的动作修订 ID（actr_ 前缀）。 |
| error（分支2).request_id | `string` / `null` | 可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。 |
| error（分支2).errors | `object[]` | 可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。 |
| error（分支2).errors[].pointer | `string` | 必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。 |
| error（分支2).errors[].detail | `string` | 必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。 |
| error（分支2).errors[].hint | `string` | 可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。 |
| error（分支2).errors[].line | `integer` | 可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| error（分支2).errors[].column | `integer` | 可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| error（分支2).status | `number` | 可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。 |
| initiator | `object` | 必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。 |
| initiator.type | `"user"` / `"api_key"` / `"agent"` / `"run"` / `"trigger"` | 必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。 |
| initiator.id | `string` | 必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。 |
| channel | `"run"` / `"console"` / `"api"` / `"internal"` / `"trigger"` | 必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。 |
| owner | `string` | 必填 / 必有；所属租户，由网关注入；按不透明字符串处理。 |
| parent | `null` / `object` | 必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。 |
| parent（分支2).id | `string` | 必填 / 必有；父运行 ID（run_ 前缀）。 |
| parent（分支2).number | `null` / `number` | 必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。 |
| parent（分支2).definition | `null` / `object` | 必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。 |
| parent（分支2).definition（分支2).namespace | `string` | 必填 / 必有；父运行所属定义的命名空间。 |
| parent（分支2).definition（分支2).name | `string` | 必填 / 必有；父运行所属定义的名字。 |
| parent_run_id | `string` / `null` | 必填 / 必有；派生出本运行的父运行 id；根运行为 null |
| root_run_id | `string` | 必填 / 必有；运行树根运行的 ID；根运行自身指向自己。 |
| depth | `number` | 必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。 |
| attach | `null` / `"wait"` / `"detach"` | 必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。 |
| deadline_at | `string` | 必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。 |
| created_at | `string` | 必填 / 必有；运行创建时间（RFC 3339 UTC）。 |
| started_at | `null` / `string` | 必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。 |
| ended_at | `null` / `string` | 必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。 |
| updated_at | `string` | 必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。 |
| heartbeat_at | `null` / `string` | 必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。 |
| cancel_requested_at | `null` / `string` | 必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。 |
| cancelled_by | `null` / `object` | 必填 / 必有；请求取消的主体；未取消或非人为取消为 null。 |
| cancelled_by（分支2).type | `"user"` / `"api_key"` / `"agent"` / `"run"` / `"trigger"` | 必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。 |
| cancelled_by（分支2).id | `string` | 必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。 |
| cancel_reason | `null` / `"user"` / `"parent_cancelled"` / `"deadline"` / `"executor_lost"` | 必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。 |
| suspend_requested_at | `null` / `string` | 必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。 |
| suspended_by | `null` / `object` | 必填 / 必有；请求暂停的主体；未暂停为 null。 |
| suspended_by（分支2).type | `"user"` / `"api_key"` / `"agent"` / `"run"` / `"trigger"` | 必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。 |
| suspended_by（分支2).id | `string` | 必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。 |
| queued_ms | `null` / `number` | 必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。 |
| run_ms | `null` / `number` | 必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。 |
| wait_ms | `null` / `number` | 必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。 |
| usage | `object` / `null` | 必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。 |
| usage（分支1).currency | `"USD"` | 必填 / 必有；金额币种，固定为 USD。 |
| usage（分支1).cost | `string` | 必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\\.[0-9]{6}$" |
| usage（分支1).pending_events | `integer` | 必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0 |
| usage（分支1).by_service | `object[]` | 必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。 |
| usage（分支1).by_service[].service | `string` | 必填 / 必有；产生用量的服务名，例如 router 或 search。 |
| usage（分支1).by_service[].cost | `string` | 必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\\.[0-9]{6}$" |
| usage（分支1).tree_cost | `string` / `null` | 必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。 |
| rerun_of | `null` / `string` | 必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。 |
| labels | `object` | 必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。 |
| trigger | `object` / `null` | 必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。 |
| trigger（分支1).id | `string` | 必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。 |
| trigger（分支1).name | `string` | 必填 / 必有；启动本运行的触发器名称。 |
| calls | `object` | 可选；expand=calls 时返回的调用记录分页：{data, next_cursor}。 不接受额外字段。 |
| calls.data | `object[]` | 必填 / 必有；本页的调用记录（Call）。 maxItems: 200 |
| calls.data[].id | `string` | 必填 / 必有；调用 ID，前缀 call_。 |
| calls.data[].run_id | `string` | 必填 / 必有；发出该调用的脚本运行 ID（run_ 前缀）。 |
| calls.data[].seq | `number` | 必填 / 必有；调用在该运行中的序号，随调用顺序递增；与 run_id 一起定位这次调用。 |
| calls.data[].target | `object` | 必填 / 必有；被调用的目标 {kind, name, revision?, version?}。 不接受额外字段。 |
| calls.data[].target.kind | `"action"` / `"script"` / `"workflow"` / `"platform_api"` | 必填 / 必有；目标类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流。 |
| calls.data[].target.name | `string` | 必填 / 必有；目标名称：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。 |
| calls.data[].target.revision | `string` | 可选；实际执行的动作修订 ID（actr_ 前缀）；仅动作调用有。 |
| calls.data[].target.version | `string` | 可选；实际运行的精确版本号；仅脚本与工作流调用有。 |
| calls.data[].args_preview | `string` | 必填 / 必有；调用参数的单行预览，由服务端截断；超过 32 KB 的原文存放在对象存储而不内联。 |
| calls.data[].result_preview | `null` / `string` | 必填 / 必有；返回值的单行预览，由服务端截断；调用结束前为 null。 |
| calls.data[].status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` | 必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。 |
| calls.data[].started_at | `string` | 必填 / 必有；调用开始的时间（RFC 3339 UTC）。 |
| calls.data[].ended_at | `null` / `string` | 必填 / 必有；调用结束的时间（RFC 3339 UTC）；仍在执行为 null。 |
| calls.data[].duration_ms | `null` / `number` | 必填 / 必有；从开始到结束的毫秒数；未结束为 null。 |
| calls.data[].error | `null` / `object` | 必填 / 必有；调用失败时的错误详情；成功或仍在执行为 null。 |
| calls.data[].error（分支2).type | `string` | 必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。 |
| calls.data[].error（分支2).code | `null` / `string` | 必填 / 必有；稳定错误码，可按码分支处理；没有为 null。 |
| calls.data[].error（分支2).title | `string` | 必填 / 必有；错误的简短标题。 |
| calls.data[].error（分支2).detail | `null` / `string` | 必填 / 必有；错误的详细说明；没有为 null。 |
| calls.data[].error（分支2).source | `null` / `object` | 必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。 |
| calls.data[].error（分支2).source（分支2).kind | `"call"` / `"task"` | 必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。 |
| calls.data[].error（分支2).source（分支2).reference | `string` | 可选；task 类型时：出错步骤的 JSON Pointer。 |
| calls.data[].error（分支2).source（分支2).seq | `number` | 可选；call 类型时：出错调用的序号（与 Call.seq 对应）。 |
| calls.data[].error（分支2).source（分支2).action | `object` | 可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。 |
| calls.data[].error（分支2).source（分支2).action.name | `string` | 必填 / 必有；动作全名 ns/name。 |
| calls.data[].error（分支2).source（分支2).action.revision | `string` | 必填 / 必有；执行的动作修订 ID（actr_ 前缀）。 |
| calls.data[].error（分支2).request_id | `string` / `null` | 可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。 |
| calls.data[].error（分支2).errors | `object[]` | 可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。 |
| calls.data[].error（分支2).errors[].pointer | `string` | 必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。 |
| calls.data[].error（分支2).errors[].detail | `string` | 必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。 |
| calls.data[].error（分支2).errors[].hint | `string` | 可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。 |
| calls.data[].error（分支2).errors[].line | `integer` | 可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| calls.data[].error（分支2).errors[].column | `integer` | 可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| calls.data[].error（分支2).status | `number` | 可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。 |
| calls.data[].child_run_id | `null` / `string` | 必填 / 必有；目标是脚本或工作流时，由本次调用启动的子运行 ID；动作与平台 API 调用为 null。 |
| calls.data[].invocation_key | `string` | 必填 / 必有；标识这一次逻辑调用的键，随调用发往下游，使至少一次语义下的重试可被去重。 |
| calls.data[].request_id | `string` / `null` | 必填 / 必有；下游响应的 X-Request-Id；尚未收到响应或响应未提供该头时为 null。 |
| calls.next_cursor | `null` / `string` | 必填 / 必有；下一页游标；没有更多为 null。 |
| tasks | `object` | 可选；expand=tasks 时返回的工作流步骤分页：{data, next_cursor}。 不接受额外字段。 |
| tasks.data | `object[]` | 必填 / 必有；本页的步骤（Task）。 maxItems: 200 |
| tasks.data[].id | `string` | 必填 / 必有；步骤执行记录的标识，按不透明字符串处理。 |
| tasks.data[].run_id | `string` | 必填 / 必有；所属运行 ID。 |
| tasks.data[].reference | `string` | 必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。 |
| tasks.data[].name | `string` | 必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。 |
| tasks.data[].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 顺序执行的步骤块。 |
| tasks.data[].iteration | `number[]` | 必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。 |
| tasks.data[].attempt | `number` | 必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。 |
| tasks.data[].status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。 |
| tasks.data[].skipped | `boolean` | 必填 / 必有；true 表示该步骤被跳过而没有实际执行。 |
| tasks.data[].started_at | `null` / `string` | 必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。 |
| tasks.data[].ended_at | `null` / `string` | 必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。 |
| tasks.data[].duration_ms | `null` / `number` | 必填 / 必有；执行耗时毫秒数；未结束为 null。 |
| tasks.data[].input | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| tasks.data[].input（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| tasks.data[].input（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| tasks.data[].input_truncated | `boolean` | 必填 / 必有；true 表示 input 超过 32 KB 已被截断。 |
| tasks.data[].output | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。 |
| tasks.data[].output（分支5).* | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| tasks.data[].output（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| tasks.data[].output_truncated | `boolean` | 必填 / 必有；输出超过内联限制而被省略时为 true。 |
| tasks.data[].error | `null` / `object` | 必填 / 必有；步骤失败时的错误详情；未失败为 null。 |
| tasks.data[].error（分支2).type | `string` | 必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。 |
| tasks.data[].error（分支2).code | `null` / `string` | 必填 / 必有；稳定错误码，可按码分支处理；没有为 null。 |
| tasks.data[].error（分支2).title | `string` | 必填 / 必有；错误的简短标题。 |
| tasks.data[].error（分支2).detail | `null` / `string` | 必填 / 必有；错误的详细说明；没有为 null。 |
| tasks.data[].error（分支2).source | `null` / `object` | 必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。 |
| tasks.data[].error（分支2).source（分支2).kind | `"call"` / `"task"` | 必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。 |
| tasks.data[].error（分支2).source（分支2).reference | `string` | 可选；task 类型时：出错步骤的 JSON Pointer。 |
| tasks.data[].error（分支2).source（分支2).seq | `number` | 可选；call 类型时：出错调用的序号（与 Call.seq 对应）。 |
| tasks.data[].error（分支2).source（分支2).action | `object` | 可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。 |
| tasks.data[].error（分支2).source（分支2).action.name | `string` | 必填 / 必有；动作全名 ns/name。 |
| tasks.data[].error（分支2).source（分支2).action.revision | `string` | 必填 / 必有；执行的动作修订 ID（actr_ 前缀）。 |
| tasks.data[].error（分支2).request_id | `string` / `null` | 可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。 |
| tasks.data[].error（分支2).errors | `object[]` | 可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。 |
| tasks.data[].error（分支2).errors[].pointer | `string` | 必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。 |
| tasks.data[].error（分支2).errors[].detail | `string` | 必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。 |
| tasks.data[].error（分支2).errors[].hint | `string` | 可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。 |
| tasks.data[].error（分支2).errors[].line | `integer` | 可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| tasks.data[].error（分支2).errors[].column | `integer` | 可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| tasks.data[].error（分支2).status | `number` | 可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。 |
| tasks.data[].action | `null` / `object` | 必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。 |
| tasks.data[].action（分支2).name | `string` | 必填 / 必有；动作全名 ns/name。 |
| tasks.data[].action（分支2).revision | `string` | 必填 / 必有；执行的动作修订 ID（actr_ 前缀）。 |
| tasks.data[].child_run | `null` / `object` | 必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。 |
| tasks.data[].child_run（分支2).id | `string` | 必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。 |
| tasks.data[].child_run（分支2).number | `null` / `number` | 必填 / 必有；子运行在其定义内的序号；临时运行为 null。 |
| tasks.data[].child_run（分支2).status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。 |
| tasks.data[].child_run（分支2).resolved_version | `null` / `string` | 必填 / 必有；子运行解析到的精确版本号；临时运行为 null。 |
| tasks.next_cursor | `null` / `string` | 必填 / 必有；下一页游标；没有更多为 null。 |
| task_groups | `object` | 可选；expand=task_groups 时返回、按 reference 聚合的步骤分页 {data, next_cursor}（循环的多次迭代合并为一行）；脚本运行为空页。 不接受额外字段。 |
| task_groups.data | `object[]` | 必填 / 必有；本页的聚合行（TaskGroup）。 maxItems: 200 |
| task_groups.data[].reference | `string` | 必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。 |
| task_groups.data[].name | `string` | 必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。 |
| task_groups.data[].count | `number` | 必填 / 必有；该 reference 下合并的执行记录条数（循环的迭代数）。 |
| task_groups.data[].status | `"running"` / `"completed"` / `"faulted"` / `"cancelled"` / `"pending"` / `"waiting"` / `"suspended"` | 必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。 |
| task_groups.data[].duration_ms | `null` / `number` | 必填 / 必有；执行耗时毫秒数；未结束为 null。 |
| task_groups.next_cursor | `null` / `string` | 必填 / 必有；下一页游标；没有更多为 null。 |
| logs | `object` | 可选；expand=logs 时返回的日志分页：{data, next_cursor}。 不接受额外字段。 |
| logs.data | `object[]` | 必填 / 必有；本页的日志行（LogLine）。 maxItems: 200 |
| logs.data[].cursor | `string` | 必填 / 必有；该行的游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。 |
| logs.data[].ts | `string` | 必填 / 必有；日志产生的时间（RFC 3339 UTC）。 |
| logs.data[].level | `"debug"` / `"info"` / `"warn"` / `"error"` | 必填 / 必有；日志级别。debug 调试信息；info 一般信息；warn 警告；error 错误。 |
| logs.data[].message | `string` | 必填 / 必有；日志文本。 |
| logs.next_cursor | `null` / `string` | 必填 / 必有；下一页游标；没有更多为 null。 |
| source | `object` | 可选；临时运行的源码快照 {language, source, sha256}。 不接受额外字段。 |
| source.language | `"ts"` / `"yaml"` | 必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。 |
| source.source | `string` | 必填 / 必有；运行时使用的完整源码（ts 或 yaml）。 |
| source.sha256 | `string` | 必填 / 必有；源码的 SHA-256 摘要，可作为发布时的 expected_source_sha256。 |
| cancel_message | `string` / `null` | 必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。 |
| input_truncated | `boolean` | 可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。 |
| output_truncated | `boolean` | 可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。 |

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

HTTP 200

```json
{
  "id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "kind": "script",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "language": "ts",
  "status": "completed",
  "progress": null,
  "current_wait": null,
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": null
  },
  "input": {
    "n": 41
  },
  "output": {
    "answer": 42
  },
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-13T05:02:40.954Z",
  "created_at": "2026-10-13T04:57:40.954Z",
  "started_at": "2026-10-13T04:57:42.283Z",
  "ended_at": "2026-10-13T04:57:42.367Z",
  "updated_at": "2026-10-13T04:57:42.367Z",
  "heartbeat_at": "2026-10-13T04:57:42.283Z",
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": null,
  "suspended_by": null,
  "queued_ms": 1329,
  "run_ms": 84,
  "wait_ms": null,
  "usage": {
    "currency": "USD",
    "cost": "0.000000",
    "pending_events": 0,
    "by_service": [],
    "tree_cost": "0.000000"
  },
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}
```

## 错误码 [#错误码]

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

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