# ProcessRetentionStatus

How long one run will be kept, and why: `GET|PUT|DELETE /processes/{processType}/{processId}/retention-lease`.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `processId` | `uuid` | The run's id. |
| `processType` | [`ProcessType`](https://docs.maitento.com/reference/types/process-type.md) | What kind of run it is. |
| `terminal` | `boolean` | True once the run has ended (`Finished`, `Error` or `Killed`). Only ended runs are ever deleted. |
| `retained` | `boolean` | True while a lease keeps the run (`lease` is set). |
| `lease` | [`ProcessRetentionLease`](https://docs.maitento.com/reference/types/process-retention-lease.md)`\| null` | The run's own lease, or the one it inherits from a retained ancestor; null when it has none. |
| `leaseEndsAtUtc` | `datetime \| null` | When the lease ends, in UTC: the time it was taken plus the longest the tenant's plan keeps a run. After that the run is kept only by `retentionHours`, from when it ended. Null without a lease, or when the plan sets no maximum. |
| `expiresAtUtc` | `datetime \| null` | When the run will be deleted, in UTC: its last update plus `retentionHours`. Null while it is retained or has not ended (a run's clock starts when it ends). |
| `retentionHours` | `integer` | How long this run is kept once it has ended and is not retained, in hours. |
| `retentionSource` | [`ProcessRetentionSource`](https://docs.maitento.com/reference/types/process-retention-source.md) | Where `retentionHours` comes from. |
| `coveredDescendants` | `integer` | How many runs below this one (the runs it started, at any depth) are kept by THIS run's own lease. Zero when it has no lease of its own. Releasing it releases them too. |
| `changed` | `boolean` | On a retain or a release: false when the run already was in the state asked for (the call changed nothing — both are idempotent). Always false on a read. |

## Example

```json
{
  "processId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "processType": "App",
  "terminal": false,
  "retained": false,
  "lease": {
    "appliedAtUtc": "2026-10-26T12:00:00.0000000Z",
    "appliedByUserId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "appliedByUserName": "...",
    "note": "...",
    "inheritedFromProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "inheritedFromProcessType": "App"
  },
  "leaseEndsAtUtc": "2026-10-26T12:00:00.0000000Z",
  "expiresAtUtc": "2026-10-26T12:00:00.0000000Z",
  "retentionHours": 0,
  "retentionSource": "PlatformDefault",
  "coveredDescendants": 0,
  "changed": false
}
```

## Where it's used

- [`runs.release`](https://docs.maitento.com/reference/api/runs.md) (`DELETE /processes/{processType}/{processId}/retention-lease`)
- [`runs.retain`](https://docs.maitento.com/reference/api/runs.md) (`PUT /processes/{processType}/{processId}/retention-lease`)
- [`runs.retention`](https://docs.maitento.com/reference/api/runs.md) (`GET /processes/{processType}/{processId}/retention-lease`)