Automation
Get a run
Read status, output and error for the id returned by praxis.automation.runs.create; output needs no expand option.
Read status, output and error for the id returned by praxis.automation.runs.create; output needs no expand option. A completed status confirms success; faulted and cancelled are terminal without successful completion. Optionally expand calls, tasks, task groups, logs or source in the same request. Pass wait (seconds, 0–60) to hold the request until the run is terminal or the time is up, instead of polling. Expanded pages hold at most 200 entries; use the ledger endpoints and cursors for subsequent pages. Workflow raise errors preserve the full type URI, status, title and detail; only internal platform exceptions are runtime errors.
GET /automation/v1/runs/{id}
Authentication
Authorization: Bearer $PRAXIS_API_KEY
Request fields
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: expand | "calls" / "tasks" / "task_groups" / "logs" / "source"[] | optional; Comma-separated, unique calls, tasks, task_groups, logs, source; these are all the valid values (output is not an expansion, the run output is the output field). Omitted by default. Expanded pages contain at most 200 entries. An invalid value returns INVALID_PARAMS listing the valid values. minItems: 1 |
| query: wait | integer | optional; Seconds to wait for the run to reach a terminal state, an integer 0–60, default 0 (return immediately). When the run is still pending, running or waiting after this time, the current run is returned with status 200; check status to tell. Above 60 or not an integer returns INVALID_PARAMS. Same meaning as wait on runs.create. minimum: 0; maximum: 60 |
Examples
Set these environment variables to your own resources:
| Variable | Source |
|---|---|
| RUN_ID | Run id; suspend/resume require a workflow; cancel requires a nonterminal run |
: "${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"import { createAutomationClient } from '@deepraxis/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);Response
HTTP 200
Success
application/json
| Field | Type | Description |
|---|---|---|
| id | string | required; Opaque run_ ID. New non-deterministic IDs have 78 characters: run_ + 10-character base36 millisecond timestamp + 64-character hexadecimal DO ID. Legacy random IDs have 46 characters; historical and deterministic IDs remain valid. Same-millisecond creation order is not guaranteed. |
| kind | "script" / "workflow" | required; Orchestration kind. script is a TypeScript script that executes once; workflow is a YAML workflow made of steps that can wait for events, timers or child runs and can be suspended. |
| number | null / number | required; Increasing sequence number of the run within its script or workflow; null for ad-hoc runs. |
| definition | null / object | required; The script or workflow {namespace, name} the run belongs to; null for ad-hoc runs created with source. |
| definition (variant 2).namespace | string | required; Namespace of the script or workflow. |
| definition (variant 2).name | string | required; Name of the script or workflow. |
| target | null / string | required; The target string as supplied at creation (for example acme/report@latest); null for ad-hoc runs. |
| resolved_version | null / string | required; Exact version the target resolved to; null for ad-hoc runs. |
| source_digest | null / string | required; Digest of the source of an ad-hoc run, usable to read that source; null for runs started from a published definition. |
| language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Run status. pending is created but not started; running is executing; waiting means a workflow is waiting on an event, timer or child run; suspended means a workflow was suspended; cancelled was cancelled; faulted failed and error says why; completed finished successfully and output holds the result. The last three are terminal. |
| progress | null / object | required; Latest progress reported by the run as {label, current, total, updated_at}; null if none was reported. |
| progress (variant 2).label | string | required; Short progress label, such as the current stage. |
| progress (variant 2).current | null / number | required; Amount completed so far, or null if not reported. |
| progress (variant 2).total | null / number | required; Total amount, or null when unknown. |
| progress (variant 2).updated_at | string | required; Time progress was last updated (RFC 3339 UTC). |
| current_wait | null / object | required; The wait point the run is currently blocked on, or null when it is not waiting. |
| current_wait (variant 2).id | string | required; Wait point id, prefixed wait_; use it as wait_id when completing an event wait. |
| current_wait (variant 2).run_id | string | required; Id (run_) of the run this wait belongs to. |
| current_wait (variant 2).kind | "event" / "timer" / "child" | required; Wait kind. event waits for an external event that can be submitted with runs.completeWait; timer waits until resume_at; child waits for a child run to finish. |
| current_wait (variant 2).state | "cancelled" / "open" / "resolved" / "expired" | required; Wait point state. open is still waiting; resolved was satisfied; expired passed its expires_at; cancelled was cancelled and can no longer be satisfied. |
| current_wait (variant 2).task | null / object | required; The workflow step {reference, name} that produced the wait; null when there is no such step. |
| current_wait (variant 2).task (variant 2).reference | string | required; JSON Pointer of the step, for example /do/2/wait_payment. |
| current_wait (variant 2).task (variant 2).name | string | required; Step name, the key in the workflow YAML. |
| current_wait (variant 2).resume_at | null / string | required; For kind=timer, the instant the run resumes (RFC 3339 UTC); null for other kinds. |
| current_wait (variant 2).event_type | null / string | required; For kind=event, the event type being awaited; null for other kinds. |
| current_wait (variant 2).child_run_id | null / string | required; For kind=child, the id of the child run being awaited; null for other kinds. |
| current_wait (variant 2).created_at | string | required; Time the wait point was created (RFC 3339 UTC). |
| current_wait (variant 2).expires_at | null / string | required; Time the wait point expires (RFC 3339 UTC), or null if it has no deadline. |
| current_wait (variant 2).resolved_at | null / string | required; Time the wait point was resolved (RFC 3339 UTC), or null if still open. |
| counters | object | required; Cumulative counters of a run. no additional fields. |
| counters.calls | number | required; Total number of calls the script made. |
| counters.action_calls | number | required; How many of those calls invoked actions. |
| counters.child_runs | number | required; Number of child runs started. |
| counters.tasks_completed | number | required; Number of workflow steps completed. |
| counters.tasks_total | null / number | required; Number of top-level steps in the workflow; null for script runs. |
| input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| error | null / object | required; Error details when the run faulted; null otherwise. |
| error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| error (variant 2).title | string | required; Short error title. |
| error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| initiator | object | required; Principal {type, id} injected by the gateway that says who initiated or acted. This service does not resolve names; the console resolves them in batches. no additional fields. |
| initiator.type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| initiator.id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| channel | "run" / "console" / "api" / "internal" / "trigger" | required; Entry channel of the request. console is the console (through its BFF); api is a public API call; internal is an internal platform call; run is a child run created by another run; trigger is started by a trigger. |
| owner | string | required; Tenant that owns the run, injected by the gateway; treat it as an opaque string. |
| parent | null / object | required; The parent run {id, number, definition} that derived this run, or null for root runs. |
| parent (variant 2).id | string | required; Id (run_) of the parent run. |
| parent (variant 2).number | null / number | required; Sequence number of the parent run within its definition; null when the parent is ad-hoc. |
| parent (variant 2).definition | null / object | required; Script or workflow {namespace, name} of the parent run; null for an ad-hoc parent. |
| parent (variant 2).definition (variant 2).namespace | string | required; Namespace of the parent run's definition. |
| parent (variant 2).definition (variant 2).name | string | required; Name of the parent run's definition. |
| parent_run_id | string / null | required; ID of the parent run that derived this run; null for root runs |
| root_run_id | string | required; Id of the root run of this run tree; a root run points to itself. |
| depth | number | required; Depth in the run tree: 0 for the root run, plus 1 per child level, at most 10. |
| attach | null / "wait" / "detach" | required; Relationship of a child run to its parent. wait means the parent waits for the child and the child's deadline is not later than the parent's; detach means the parent does not wait and the child is not cancelled when the parent is; null for root runs. |
| deadline_at | string | required; Deadline of the run (RFC 3339 UTC): creation time plus deadline_seconds (scripts default to and are capped at 300 seconds; workflows default to 86400 and are capped at 604800), and an awaited child ends at least 1 second before its parent's deadline. |
| created_at | string | required; Time the run was created (RFC 3339 UTC). |
| started_at | null / string | required; Time execution started (RFC 3339 UTC), or null while still queued. |
| ended_at | null / string | required; Time the run reached a terminal status (RFC 3339 UTC), or null while it is still active. |
| updated_at | string | required; Time the run record was last updated (RFC 3339 UTC). |
| heartbeat_at | null / string | required; Time of the executor's last liveness signal (RFC 3339 UTC), or null before the run starts. |
| cancel_requested_at | null / string | required; Time the cancellation was requested (RFC 3339 UTC), or null. |
| cancelled_by | null / object | required; Principal that requested cancellation, or null if not cancelled or not requested by a principal. |
| cancelled_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| cancelled_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| cancel_reason | null / "user" / "parent_cancelled" / "deadline" / "executor_lost" | required; Why the run was cancelled. user is a user request; parent_cancelled is a cascade from a cancelled parent run; deadline means the deadline passed; executor_lost means the executor was lost; null if not cancelled. |
| suspend_requested_at | null / string | required; Time suspension of the workflow was requested (RFC 3339 UTC), or null. |
| suspended_by | null / object | required; Principal that requested suspension, or null. |
| suspended_by (variant 2).type | "user" / "api_key" / "agent" / "run" / "trigger" | required; Principal type. user is a signed-in user; api_key is a platform API key; agent is an agent; run is an action performed by a run itself (for example a parent run); trigger is a trigger. |
| suspended_by (variant 2).id | string | required; Principal identifier whose meaning follows type: a user, API key, agent, run or trigger id. Treat it as an opaque string. |
| queued_ms | null / number | required; Milliseconds between creation and the start of execution; null until the run starts. |
| run_ms | null / number | required; Milliseconds spent executing, excluding time spent waiting on wait points; fixed once the run ends. |
| wait_ms | null / number | required; Total milliseconds spent waiting on wait points; null before any wait. |
| usage | object / null | required; Returned only in single-run details (including expand); null in lists. Runs themselves are free; these are actual charges for capabilities such as models and search called during the run, attributed by call. Unrated usage is included later. Aggregation failure or timeout (1.5 seconds) returns null while details still return 200. |
| usage (variant 1).currency | "USD" | required; Charge currency, always USD. |
| usage (variant 1).cost | string | required; Rated actual charges for this run alone, excluding descendants, as an exact dollar decimal string with six fractional digits; 0.000000 when there is no usage. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).pending_events | integer | required; Number of this run's own unrated usage events whose charges will be included later. minimum: 0 |
| usage (variant 1).by_service | object[] | required; This run's actual charges grouped by service, each with service and cost (a six-decimal dollar string); empty when there is no usage. |
| usage (variant 1).by_service[].service | string | required; Name of the service that incurred the usage, for example router or search. |
| usage (variant 1).by_service[].cost | string | required; Rated actual charges for that service as an exact dollar decimal string with six fractional digits. pattern: "^[0-9]+\.[0-9]{6}$" |
| usage (variant 1).tree_cost | string / null | required; Rated actual charges for the entire run tree including the root, as a six-decimal dollar string; null for child runs. |
| rerun_of | null / string | required; If this run was created by re-running another run, that run's id (run_); otherwise null. |
| labels | object | required; User labels and system labels; trigger runs support 64 user labels, excluding system labels. |
| trigger | object / null | required; Trigger {id, name} that started this run, or null when it was not started by a trigger. |
| trigger (variant 1).id | string | required; Id (trg_) of the trigger that started this run. |
| trigger (variant 1).name | string | required; Name of the trigger that started this run. |
| calls | object | optional; Page of call records returned with expand=calls: {data, next_cursor}. no additional fields. |
| calls.data | object[] | required; Call records on this page. maxItems: 200 |
| calls.data[].id | string | required; Call id, prefixed call_. |
| calls.data[].run_id | string | required; Id (run_) of the script run that made the call. |
| calls.data[].seq | number | required; Position of the call within the run, increasing in call order; together with run_id it locates the call. |
| calls.data[].target | object | required; The target that was called: {kind, name, revision?, version?}. no additional fields. |
| calls.data[].target.kind | "action" / "script" / "workflow" / "platform_api" | required; Target kind. action is an action; platform_api is a platform API operation; script is a script; workflow is a workflow. |
| calls.data[].target.name | string | required; Target name: ns/name for an action, the operation name for a platform API, ns/name for a script or workflow. |
| calls.data[].target.revision | string | optional; Id (actr_) of the action revision that executed; present only for action calls. |
| calls.data[].target.version | string | optional; Exact version that ran; present only for script and workflow calls. |
| calls.data[].args_preview | string | required; Single-line preview of the call arguments, truncated on the server; payloads over 32 KB are kept in object storage rather than inline. |
| calls.data[].result_preview | null / string | required; Single-line preview of the returned value, truncated on the server; null until the call ends. |
| calls.data[].status | "running" / "completed" / "faulted" / "cancelled" | required; Call status. running means still executing; completed means it returned normally; faulted means it failed and error explains why; cancelled means it was stopped because the run was cancelled. |
| calls.data[].started_at | string | required; Time the call started (RFC 3339 UTC). |
| calls.data[].ended_at | null / string | required; Time the call ended (RFC 3339 UTC), or null while it is running. |
| calls.data[].duration_ms | null / number | required; Milliseconds from start to end, or null while the call is running. |
| calls.data[].error | null / object | required; Error details when the call failed; null if it succeeded or is still running. |
| calls.data[].error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| calls.data[].error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| calls.data[].error (variant 2).title | string | required; Short error title. |
| calls.data[].error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| calls.data[].error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| calls.data[].error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| calls.data[].error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| calls.data[].error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| calls.data[].error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| calls.data[].error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| calls.data[].error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| calls.data[].error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| calls.data[].error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| calls.data[].error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| calls.data[].error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| calls.data[].error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| calls.data[].error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| calls.data[].error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| calls.data[].error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| calls.data[].child_run_id | null / string | required; When the target is a script or workflow, the id of the child run this call started; null for action and platform API calls. |
| calls.data[].invocation_key | string | required; Key identifying this logical call, sent downstream so that retries under at-least-once delivery can be deduplicated. |
| calls.data[].request_id | string / null | required; Downstream response X-Request-Id, or null before a response or when the header is absent. |
| calls.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| tasks | object | optional; Page of workflow steps returned with expand=tasks: {data, next_cursor}. no additional fields. |
| tasks.data | object[] | required; Steps on this page. maxItems: 200 |
| tasks.data[].id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| tasks.data[].run_id | string | required; ID of the owning run. |
| tasks.data[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| tasks.data[].name | string | required; Step name, the key of the step in the workflow YAML. |
| tasks.data[].kind | "run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do" | required; Workflow step kind. call invokes an action; run starts a child script or workflow; wait pauses for a duration; set assigns variables; for loops; fork runs parallel branches; try is a block with catch; switch branches on conditions; emit publishes an event; raise throws an error; listen waits for an event; do is a block of sequential steps. |
| tasks.data[].iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| tasks.data[].attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| tasks.data[].status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| tasks.data[].skipped | boolean | required; true when the step was skipped without actually executing. |
| tasks.data[].started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| tasks.data[].ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| tasks.data[].duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| tasks.data[].input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| tasks.data[].input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| tasks.data[].output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| tasks.data[].output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| tasks.data[].output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| tasks.data[].error | null / object | required; Error details when the step failed; null otherwise. |
| tasks.data[].error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| tasks.data[].error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| tasks.data[].error (variant 2).title | string | required; Short error title. |
| tasks.data[].error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| tasks.data[].error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| tasks.data[].error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| tasks.data[].error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| tasks.data[].error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| tasks.data[].error (variant 2).source (variant 2).action | object | optional; The failing action {name, revision}; present only when the error came from an action. no additional fields. |
| tasks.data[].error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| tasks.data[].error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| tasks.data[].error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| tasks.data[].error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| tasks.data[].error (variant 2).errors[].pointer | string | required; RFC 6901 field pointer. TypeScript source diagnostics use /source for scripts or /implementation/source for actions; line/column are separate, not pointer segments. |
| tasks.data[].error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| tasks.data[].error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| tasks.data[].error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| tasks.data[].error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| tasks.data[].error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| tasks.data[].action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| tasks.data[].action (variant 2).name | string | required; Full action name, ns/name. |
| tasks.data[].action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| tasks.data[].child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| tasks.data[].child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| tasks.data[].child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| tasks.data[].child_run (variant 2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Status of the child run. pending is not started; running is executing; waiting is waiting; suspended is suspended; cancelled was cancelled; faulted failed; completed succeeded. An awaited child is updated to its terminal status when it ends; a detached child keeps the status at launch. |
| tasks.data[].child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| tasks.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| task_groups | object | optional; Page of steps aggregated by reference, returned with expand=task_groups as {data, next_cursor} (loop iterations collapse into one row); an empty page for script runs. no additional fields. |
| task_groups.data | object[] | required; Aggregated rows on this page. maxItems: 200 |
| task_groups.data[].reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| task_groups.data[].name | string | required; Step name, the key of the step in the workflow YAML. |
| task_groups.data[].count | number | required; Number of execution records merged under this reference (the loop iteration count). |
| task_groups.data[].status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | required; Step status, with the same values as run status. pending is not started; running is executing; waiting is waiting on an event, timer or child run; suspended is held because the run was suspended; cancelled was cancelled; faulted failed; completed succeeded. |
| task_groups.data[].duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| task_groups.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| logs | object | optional; Page of log lines returned with expand=logs: {data, next_cursor}. no additional fields. |
| logs.data | object[] | required; Log lines on this page. maxItems: 200 |
| logs.data[].cursor | string | required; Cursor of this line; use it as cursor to page, or as Last-Event-ID to resume an SSE stream. |
| logs.data[].ts | string | required; Time the line was logged (RFC 3339 UTC). |
| logs.data[].level | "debug" / "info" / "warn" / "error" | required; Log level. debug is diagnostic detail; info is general information; warn is a warning; error is an error. |
| logs.data[].message | string | required; Log message text. |
| logs.next_cursor | null / string | required; Cursor for the next page, or null when there are no more. |
| source | object | optional; Source snapshot of an ad-hoc run as {language, source, sha256}. no additional fields. |
| source.language | "ts" / "yaml" | required; Source language. ts is a TypeScript script; yaml is workflow YAML. |
| source.source | string | required; Full source (ts or yaml) the run used. |
| source.sha256 | string | required; SHA-256 digest of the source; usable as expected_source_sha256 when publishing. |
| cancel_message | string / null | required; User cancellation note (1–500 characters), or null when omitted. The cancel_reason enum is unchanged. |
| input_truncated | boolean | optional; True when the list omits blob-backed input, setting input to null; inline values remain intact and run details return the full value. |
| output_truncated | boolean | optional; True when the list omits blob-backed output, setting output to null; inline values remain intact and run details return the full value. |
Measured response
HTTP 200
{
"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"
}
}Errors
| HTTP | Codes and description |
|---|---|
| 400 | INVALID_PARAMS: Invalid request parameters, path, cursor, or body format. |
| 404 | RUN_NOT_FOUND: The run does not exist or is not visible to this tenant. |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
Authentication and common errors · Retain the X-Request-Id response header for troubleshooting.