Automation
List run tasks
Page through the task ledger.
Page through the task ledger. include=planned adds unexecuted top-level steps; group_by=reference aggregates count, status and duration by task reference.
GET /automation/v1/runs/{id}/tasks
Authentication
Authorization: Bearer $PRAXIS_API_KEY
Request fields
| Parameter | Type | Description |
|---|---|---|
| path: id | string | required; Run ID (run_). |
| query: limit | integer | optional; Run ledger page size: integer 1–200, default 50; other collections are capped at 100. minimum: 1; maximum: 200 |
| query: cursor | string | optional; Opaque next_cursor from the previous page; keep the original filters when paging. |
| query: include | "planned" | optional; Only planned is supported, adding unexecuted top-level steps; omit to read existing tasks only. |
| query: group_by | "reference" | optional; Only reference is supported, grouping loop executions by task reference; omit for individual tasks. |
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}/tasks" \
-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.tasks.list({
"path": {
"id": env("RUN_ID")
}
});
console.log(result);Response
HTTP 200
Success
application/json
| Field | Type | Description |
|---|---|---|
| data | object / object[] | required; Workflow step records, or TaskGroup rows aggregated by reference when group_by=reference on this page, in execution order. |
| data[] (variant 1).id | string | required; Identifier of this step execution record; treat it as an opaque string. |
| data[] (variant 1).run_id | string | required; ID of the owning run. |
| data[] (variant 1).reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| data[] (variant 1).name | string | required; Step name, the key of the step in the workflow YAML. |
| data[] (variant 1).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. |
| data[] (variant 1).iteration | number[] | required; Current iteration indexes of enclosing for loops, outermost first; an empty array outside loops. |
| data[] (variant 1).attempt | number | required; Attempt number of this execution; it increases when the step is re-executed by a retry. |
| data[] (variant 1).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. |
| data[] (variant 1).skipped | boolean | required; true when the step was skipped without actually executing. |
| data[] (variant 1).started_at | null / string | required; Time the step started (RFC 3339 UTC), or null. |
| data[] (variant 1).ended_at | null / string | required; Time the step ended (RFC 3339 UTC), or null. |
| data[] (variant 1).duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| data[] (variant 1).input | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 1).input (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).input (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).input_truncated | boolean | required; true when input exceeded 32 KB and was truncated. |
| data[] (variant 1).output | null / string / number / boolean / object / JSON[] | required; Any JSON value: null, boolean, number, string, array or object. |
| data[] (variant 1).output (variant 5).* | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).output (variant 6)[] | null / string / number / boolean / object / JSON[] | Recursive JSON value. |
| data[] (variant 1).output_truncated | boolean | required; True when output is omitted because it exceeds the inline limit. |
| data[] (variant 1).error | null / object | required; Error details when the step failed; null otherwise. |
| data[] (variant 1).error (variant 2).type | string | required; Platform error category, or the verbatim URI defined by a workflow raise. |
| data[] (variant 1).error (variant 2).code | null / string | required; Stable error code callers can branch on, or null. |
| data[] (variant 1).error (variant 2).title | string | required; Short error title. |
| data[] (variant 1).error (variant 2).detail | null / string | required; Detailed explanation of the error, or null. |
| data[] (variant 1).error (variant 2).source | null / object | required; Where the error happened: a workflow step or script call; null when unknown. |
| data[] (variant 1).error (variant 2).source (variant 2).kind | "call" / "task" | required; Location kind. task is a workflow step; call is a call in a script. |
| data[] (variant 1).error (variant 2).source (variant 2).reference | string | optional; For task: the JSON Pointer of the failing step. |
| data[] (variant 1).error (variant 2).source (variant 2).seq | number | optional; For call: sequence number of the failing call (matches Call.seq). |
| data[] (variant 1).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. |
| data[] (variant 1).error (variant 2).source (variant 2).action.name | string | required; Full action name, ns/name. |
| data[] (variant 1).error (variant 2).source (variant 2).action.revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 1).error (variant 2).request_id | string / null | optional; X-Request-Id of the downstream response that caused the failure; null or omitted when unavailable. |
| data[] (variant 1).error (variant 2).errors | object[] | optional; Field validation errors with RFC 6901 pointers and Chinese correction details. |
| data[] (variant 1).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. |
| data[] (variant 1).error (variant 2).errors[].detail | string | required; Chinese correction text saying what is wrong at this location and how to fix it. |
| data[] (variant 1).error (variant 2).errors[].hint | string | optional; Optional extra hint giving an actionable next step, such as using a different endpoint. |
| data[] (variant 1).error (variant 2).errors[].line | integer | optional; Line number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 1).error (variant 2).errors[].column | integer | optional; Column number, 1-based; present only when a source location is available. minimum: 1 |
| data[] (variant 1).error (variant 2).status | number | optional; Optional HTTP-style status declared by a workflow raise; platform errors may omit it. |
| data[] (variant 1).action | null / object | required; Action {name, revision} a call step executed; null for other steps. |
| data[] (variant 1).action (variant 2).name | string | required; Full action name, ns/name. |
| data[] (variant 1).action (variant 2).revision | string | required; Id (actr_) of the action revision that ran. |
| data[] (variant 1).child_run | null / object | required; Summary {id, number, status, resolved_version} of the child run a run step started; null for other steps. |
| data[] (variant 1).child_run (variant 2).id | string | required; Id (run_) of the child run, readable as soon as it is created. |
| data[] (variant 1).child_run (variant 2).number | null / number | required; Sequence number of the child run within its definition; null for ad-hoc runs. |
| data[] (variant 1).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. |
| data[] (variant 1).child_run (variant 2).resolved_version | null / string | required; Exact version the child run resolved to; null for ad-hoc runs. |
| data[] (variant 2).reference | string | required; JSON Pointer of the step in the workflow document, for example /do/0/start. |
| data[] (variant 2).name | string | required; Step name, the key of the step in the workflow YAML. |
| data[] (variant 2).count | number | required; Number of execution records merged under this reference (the loop iteration count). |
| data[] (variant 2).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. |
| data[] (variant 2).duration_ms | null / number | required; Execution time in milliseconds, or null until it ends. |
| next_cursor | null / string | required; Cursor for the next page: pass it unchanged as cursor with the same filters; null when there are no more pages. No total is returned. |
Measured response
HTTP 200
{
"data": [],
"next_cursor": null
}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.