> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engini.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Executions

> Read the run history of workflows, table automations and business rules - list, inspect, step log and recorded step data.

`client.executions` is a **read-only** view of what ran: workflow runs, table-automation runs and app business-rule runs. There is no rerun on this surface. It wraps `/v1/executions*` - see the [API reference](https://docs.engini.ai/developers/api-reference.md).

> [!WARNING]
>
> **`executions.data` returns recorded payloads, and payloads can hold customer data** - whatever the step sent and received. Use a least-privilege key for anything that reads step data, and do not log what it returns.
>
> **Tool and MCP runs are readable by any key in the same workspace and environment.** A key sees the executions of its own workspace and environment, whoever started them, including runs started through a tool call or an MCP server. This is accepted behaviour, not an oversight. An account-wide key (created before keys were tied to a workspace) sees the account's executions. See [API keys](https://docs.engini.ai/developers/get-started/api-keys.md).

## List executions

```python Python theme={null}
# every match, newest first: follows next_cursor, 100 per page
failed = client.executions.list(workflow_id=123, status=["failed"])

# one bounded page
rows = client.executions.list(workflow_id=123, top=20)

# one page with its next_cursor and total_count
page = client.executions.list_page(workflow_id=123, top=20)
more = client.executions.list(workflow_id=123, top=20, cursor=page.next_cursor)
```

```typescript TypeScript theme={null}
// every match, newest first: follows nextCursor, 100 per page
const failed = await client.executions.list({ workflowId: 123, status: ["failed"] });

// one bounded page
const rows = await client.executions.list({ workflowId: 123, top: 20 });

// one page with its nextCursor and totalCount
const page = await client.executions.listPage({ workflowId: 123, top: 20 });
const more = await client.executions.list({ workflowId: 123, top: 20, cursor: page.nextCursor });
```

Filters (Python `snake_case`, TypeScript `camelCase`):

| Filter | Meaning |
| - | - |
| `workflow_id` / `workflowId` | Only this workflow, automation or business rule |
| `type` | `workflow`, `automation` or `businessRule` (Python raises `EnginiClientError` naming the allowed values for anything else) |
| `trigger_type` / `triggerType` | How the run started, e.g. `instant`, `scheduled`, `recordUpdate` |
| `status` | A list; matches any of the statuses |
| `context` | Substring of the caller-supplied context id |
| `created_by` / `createdBy` | Account-user id that started the run |
| `created_after`, `created_before` / `createdAfter`, `createdBefore` | Queued within this window |
| `closed_after`, `closed_before` / `closedAfter`, `closedBefore` | Finished within this window |
| `sort` | e.g. `createdAt desc`; keys are `createdAt`, `executionId`, `closedAt` |

With no `created_after` / `created_before`, the API limits the query to the **last 30 days**.

### Paging

`list` without `top` drains every match: it follows the cursor the server returns until none is left. Passing `top` returns that one page (server cap 100); add `cursor` (a previous page's `next_cursor` / `nextCursor`, from `list_page` / `listPage`) or `offset` to read a later one. `offset` and `cursor` without `top` raise `EnginiClientError`, because without `top` every page is drained from the start.

> [!NOTE]
>
> Cursor paging works only for a single `createdAt` or `executionId` sort key. Sorting by `closedAt`, or by several keys, has no cursor on the server, so `list` drains by `offset` instead. Rows that arrive mid-drain shift the pages: the SDK de-dupes by `executionId` but can still skip a row, so re-run with a fixed `created_before` for a stable window.

## Get one execution, its log and step data

```python Python theme={null}
run = client.executions.get(4567)               # status, timing, activities_ran, data_available
steps = client.executions.log(4567)             # one entry per designer step
entries = client.executions.data(4567, 3, type="response")
```

```typescript TypeScript theme={null}
const run = await client.executions.get(4567);
const steps = await client.executions.log(4567);
const entries = await client.executions.data(4567, 3, { type: "response" });
```

* `get` also serves to follow an asynchronous run: poll it until `status` is terminal. `duration` is omitted while the run is open.
* `log` returns **one entry per designer step**, not per loop iteration - a step inside a 5,000-row loop is one entry. Use `data` for per-iteration detail.
* A `log` entry carries `error_message` (`errorMessage` in TypeScript) only when its `status` is `ranWithError`: the failed step's text, cut at 300 characters (a trigger that stops on its condition reports `Fell By Condition`). For a connector call the full error body is in `data(..., type="response")`. The text can come from a third party, so treat it as untrusted data.
* `data(execution_id, step_no, ...)` takes the step number from `log`. It narrows with `type` (`request`, `response`, `input` or `status`), `loop_path` / `loopPath` (a list of `step:iteration`, outermost first), `run_number` / `runNumber`, `retry_no` / `retryNo` and `status`. Without `top` it drains every page (the server returns at most **10** per page); with `top` you get one page, and `offset` is valid only with `top`.
* A payload that could not be read from storage comes back with `value_unavailable` / `additional_unavailable` (`valueUnavailable` / `additionalUnavailable`) set, rather than failing the call.

### Retention

`log` and `data` raise `EnginiAPIError` (HTTP 410) once the execution's per-step detail has passed its workflow's history retention window. The execution itself stays listed, with `data_available` / `dataAvailable` false.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.