# Runs (all kinds)

9 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `runs.list`

```http
GET /processes
```

Runs, newest first, as compact summaries. Await it for the first page, or iterate every run: `for await (const run of mt.runs.list({ state: "Active" })) { … }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fprocesses).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `ids` | `string` |  | CSV of process ids (at most 50): only these runs, whatever their type. Combines with every other filter. Unknown ids, and ids of another tenant's runs, are simply absent from the page. |
| `types` | `string` |  | CSV of `App\|Interaction\|Capsule\|CodePipeline` (case-insensitive). Empty means all four. |
| `state` | `string` |  | `active\|waiting\|terminal` (case-insensitive). |
| `statuses` | `string` |  | CSV of raw, type-specific status names (case-insensitive), e.g. `Running,PendingApproval`. |
| `definitionId` | `uuid` |  | Only runs of this interaction, app, capsule or code pipeline (its id). |
| `namespaceId` | `uuid` |  | Runs of any definition in this namespace. |
| `namespace` | `string[]` |  | Namespace names — repeatable (`namespace=a&namespace=b`), and each value may also be a CSV: runs of any definition in any of them, including deleted definitions. Names are exact (case-sensitive) and resolved in your tenant only; a name that matches no namespace there matches nothing — if no name matches, the page is empty. At most 50 distinct names. Combines with `namespaceId` (AND). |
| `rootProcessId` | `uuid` |  | Only the runs in this run's tree: the runs whose `rootProcessId` is this. |
| `parentProcessId` | `uuid` |  | Only the runs this run started directly: the runs whose `parentProcessId` is this. |
| `resumeFromProcessId` | `uuid` |  | Only the runs restarted from this one (their `resumeFromProcessId`). Only code pipeline runs are ever restarted as a new run, so with this filter no app, interaction or capsule run matches. |
| `retained` | `boolean` |  | `true`: only runs a retention lease keeps (their own lease or one inherited from a retained ancestor); `false`: only runs without one. Absent: both. |
| `createdAfter` | `datetime` |  | Inclusive lower bound on creation time. |
| `createdBefore` | `datetime` |  | Exclusive upper bound on creation time. |
| `cursor` | `string` |  | The `nextCursor` of the previous page. |
| `limit` | `integer` |  | 1–200, default 50. |

**Response:** [`ProcessPage`](https://docs.maitento.com/reference/types/process-page.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/processes" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
for await (const run of mt.runs.list({ types: ["Interaction"], state: "Active" })) console.log(run.id, run.status);
```
```python title="Python"
mt.runs.list(state="Terminal", limit=50)
```

## `runs.get`

```http
GET /processes/by-id/{id}
```

One run of any kind, as a summary. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fprocesses%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`ProcessSummary`](https://docs.maitento.com/reference/types/process-summary.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/processes/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const summary = await mt.runs.get("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");
```
```python title="Python"
mt.runs.get("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")
```

## `runs.summary`

```http
GET /processes/summary
```

The runs dashboard: counts, active runs, failures, throughput and tokens over the last `hours` (1–168).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fprocesses%2Fsummary).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `hours` | `integer` |  |  |
| `namespaceId` | `uuid` |  |  |
| `namespace` | `string[]` |  |  |

**Response:** [`ProcessDashboard`](https://docs.maitento.com/reference/types/process-dashboard.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/processes/summary" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const dashboard = await mt.runs.summary({ hours: 24 });
```
```python title="Python"
mt.runs.summary(hours=24)
```

## `runs.kill`

```http
POST /processes/{processType}/{processId}/kill
```

Kills a run of any kind.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fprocesses%2F%7BprocessType%7D%2F%7BprocessId%7D%2Fkill).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | yes |  |
| `processId` | `uuid` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X POST "https://api.maitento.com/processes/<processType>/<processId>/kill" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.runs.kill("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });
```
```python title="Python"
mt.runs.kill("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")
```

## `runs.lane`

```http
GET /processes/{processType}/{processId}/lane
```

Whether a run is waiting for a lane before it starts: since when, why, and how many of your runs are ahead of it.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fprocesses%2F%7BprocessType%7D%2F%7BprocessId%7D%2Flane).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | yes |  |
| `processId` | `uuid` | yes |  |

**Response:** [`RunLaneWait`](https://docs.maitento.com/reference/types/run-lane-wait.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/processes/<processType>/<processId>/lane" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const wait = await mt.runs.lane("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });
```
```python title="Python"
mt.runs.lane("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")
```

## `runs.release`

```http
DELETE /processes/{processType}/{processId}/retention-lease
```

Releases a run's retention lease: it is then cleared up like any other.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fprocesses%2F%7BprocessType%7D%2F%7BprocessId%7D%2Fretention-lease).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | yes |  |
| `processId` | `uuid` | yes |  |

**Response:** [`ProcessRetentionStatus`](https://docs.maitento.com/reference/types/process-retention-status.md) (200)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/processes/<processType>/<processId>/retention-lease" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.runs.release("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });
```
```python title="Python"
mt.runs.release("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")
```

## `runs.retention`

```http
GET /processes/{processType}/{processId}/retention-lease
```

How long a run will be kept, and its retention lease.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fprocesses%2F%7BprocessType%7D%2F%7BprocessId%7D%2Fretention-lease).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | yes |  |
| `processId` | `uuid` | yes |  |

**Response:** [`ProcessRetentionStatus`](https://docs.maitento.com/reference/types/process-retention-status.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/processes/<processType>/<processId>/retention-lease" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const retention = await mt.runs.retention("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });
```
```python title="Python"
mt.runs.retention("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")
```

## `runs.retain`

```http
PUT /processes/{processType}/{processId}/retention-lease
```

Keeps a run (and the runs under it) until released. Idempotent.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=PUT%20%2Fprocesses%2F%7BprocessType%7D%2F%7BprocessId%7D%2Fretention-lease).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | yes |  |
| `processId` | `uuid` | yes |  |

**Request body:** [`ProcessRetentionLeaseRequest`](https://docs.maitento.com/reference/types/process-retention-lease-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `note` | `string \| null` |  | Optional: why the run is being retained (shown with the lease). Trimmed; empty is the same as none. Ignored when the run already has its own lease — a retain never rewrites an existing lease. |

**Response:** [`ProcessRetentionStatus`](https://docs.maitento.com/reference/types/process-retention-status.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/processes/<processType>/<processId>/retention-lease" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"note":"..."}'
```
```ts title="TypeScript"
await mt.runs.retain("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction", note: "Evidence for ticket 4211" });
```
```python title="Python"
mt.runs.retain("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction", note="Customer escalation")
```

## `runs.webUsage`

```http
GET /web/usage/by-process/{processId}
```

The metered web searches and fetches a run made.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fweb%2Fusage%2Fby-process%2F%7BprocessId%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `processId` | `uuid` | yes |  |

**Response:** [`WebUsageRecord`](https://docs.maitento.com/reference/types/web-usage-record.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/web/usage/by-process/<processId>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const webCalls = await mt.runs.webUsage("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");
```
```python title="Python"
mt.runs.web_usage("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")
```