# List run tasks (/en/docs/api/native/automation/listRunTasks)





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 [#authentication]

`Authorization: Bearer $PRAXIS_API_KEY`

## Request fields [#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 [#examples]

[SDK installation and example environment](/en/docs/api/native/automation)

Set these environment variables to your own resources:

| Variable | Source |
| --- | --- |
| RUN_ID | [Run id; suspend/resume require a workflow; cancel requires a nonterminal run](/en/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 '@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 [#response]

### HTTP 200 [#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 [#measured-response]

HTTP 200

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

## Errors [#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](/en/docs/api/errors) · Retain the `X-Request-Id` response header for troubleshooting.