---
title: Data retention
description: How long the harness keeps tasks, how to delete them, put them
  under a legal hold, or keep no content at all with zero-retention.
url: https://hexelstudio.com/docs/harness/data-retention
---

Each environment has data settings: how long finished tasks are kept, whether their content is erased as soon as they end, and whether everything is held.

```bash
hexel harness settings
hexel harness settings set --retention-days 90
hexel harness settings set --zero-retention=true
hexel harness settings set --legal-hold=true
```

`GET /harness/environments/settings` and `PUT /harness/environments/settings` read and change them; a field you leave out keeps its value. Changing them needs `harness:environment:admin` (Admins and Owners).

| Setting | Default | Description |
| --- | --- | --- |
| `retention_days` | 30 | Finished tasks are deleted this many days after they last changed. 1 to 3650. |
| `zero_retention` | `false` | Erase a task's content in the runtime as soon as it ends. |
| `legal_hold` | `false` | Hold the whole environment: nothing is pruned or deleted. |
| `delete_artifacts` | `false` | Not available yet (`409 artifact_deletion_unavailable`): artifacts stay in your storage. |

## Retention

Every minute, finished tasks (`succeeded`, `failed`, `cancelled`, `budget_exhausted`) that last changed more than `retention_days` ago, and are not held, are deleted as if you had deleted them. A member of a swarm that is still open is kept until later.

<Warning>
Retention is on in the private preview. Tasks finished more than 30 days ago are deleted in every environment that does not set `retention_days`. Set it, or a legal hold, before that matters.
</Warning>

## Delete a task

```bash
hexel harness task delete tsk_123
```

`DELETE /harness/tasks/{id}` removes the task and everything under it from the control plane in one step and answers `202` with `{task_id, erasures}`: one erasure for each runtime that holds its runs, which then erases what it holds. `GET /harness/erasures` (`hexel harness erasures`) lists the environment's erasures with their state: `pending`, `done` or `failed`. The task's own event stream ends with the task.

- A task under a legal hold cannot be deleted (`409 legal_hold`).
- A [fork](https://hexelstudio.com/docs/harness/fork-and-replay) is a task of its own: it is not deleted with its parent. A fork of the task that has not started yet fails (`parent_erased`).
- A task whose runs never reached a runtime has one erasure, `done` at once.

### What is erased

On the private preview's hosted runtime, each run's erasure is carried out by a step of its own in your organization's runner pool. It stops what is left of the run, destroys its sandboxes, erases its sessions, drops the run's own storage (its ledger and job queue), and erases the task's records and its task-scoped memory. The erasure is then `done`, and its `result` reads `{"sessions": <n>, "artifacts": "kept"}`.

An erasure that cannot finish yet stays `pending` with its last reason in `failed_reason`, and is tried again until it is done.

### What stays

- **Artifacts** stay in your storage: the result says `"artifacts": "kept"`, and `delete_artifacts` is not available yet.
- **Titan's records** of the task's sessions stay in your organization's Titan: their Agent Ledger and Session Store entries, which hold ids, digests and decisions, and no harness content in the default metadata-only data mode.
- **A sandbox** the erasure could not reach is not destroyed by it: it ends at its timeout (one hour), and the result counts it in `sandboxes_left_to_timeout`.
- **A board swarm's shared content** goes with the erasure of a member task when the swarm is no longer running and no task of it is left. It stays in the runner pool when the swarm's last task is deleted while the swarm is still running, or when the last task deleted never ran on the hosted runtime. This is a known gap.

## Legal hold

```bash
hexel harness task hold tsk_123
hexel harness task hold tsk_123 --release
```

`PUT /harness/tasks/{id}/hold` `{"hold": true}` holds one task (`held_at` on the task); `legal_hold` in the settings holds the whole environment. A held task is never pruned, cannot be deleted, and its content is never erased by zero-retention. A hold that answered `200` applies to every deletion after it. Holding a task whose content is already being erased is refused (`409 erasure_in_progress`).

## Zero-retention

In a zero-retention environment, when a task ends, the runtime erases its runs' sessions and kept outputs, and the control plane then removes the task's goal, inputs and command content. The task's stream gets `task.erased` `{scope: "content", by: "zero_retention"}`, and the task shows `erased_at`.

- What stays: ids, states, costs, digests and sizes, and in the runtime the run ids, Titan approval ids and artifact digests. Artifacts stay in your storage.
- Turning zero-retention on needs the metadata-only data mode, the default (`409 zero_retention_unavailable` otherwise).
- A task that ran out of budget is not erased, since a resume continues it.
- An erased task cannot be retried or resumed (`409 task_erased`), forked (`409 parent_zero_retention`), or used by `inputs_from` (`409 inputs_from_unavailable`).
- A swarm member's output kept for its reduce step or lead stays until the swarm's task is deleted.
