# Data Retention

> What the kit deletes on its own, when, and how to add retention for your tables: cleanup tasks for old rows, purge targets for rows a deleted user or organization leaves behind.

*Canonical: https://makerkit.dev/docs/void-cloudflare/cleanup/overview*

---

Rows that nobody needs any more are deleted in the background, in small batches, as [outbox jobs](../outbox/overview). Two kinds of work do it:

- **Cleanup tasks** delete rows past a retention window, once a day: expired sessions, old exports, finished invitations.
- **Purges** delete everything a deleted user or organization owned in tables too big to cascade: events, logs, messages.

Both only ever delete, one bounded batch per transaction (1000 rows by default), so a backlog of millions never turns into one long lock.

## What the Kit Deletes

Every day at 03:00 UTC (`apps/web/crons/cleanup.ts`), the kit's tasks run:

| Task | Deletes | Keeps |
|---|---|---|
| `kit.sessions` | Sessions expired over a day ago | Live sessions |
| `kit.verifications` | Email and reset tokens expired over a day ago | Unexpired tokens |
| `kit.step-up` | Step-up codes expired over a day ago | Codes the hourly and daily limits still count |
| `kit.rate-limits` | Rate-limit counters idle over a day | Counters inside any rate-limit window |
| `kit.invitations` | Accepted, canceled, rejected and expired invitations, 30 days after they were sent | Pending invitations that haven't expired, whatever their age |

Retention is your responsibility: if you must keep these longer (an audit duty), lengthen or turn off any of them in `apps/web/config/cleanup.config.server.ts` ([Cleanup Tasks](./tasks#changing-the-kits-tasks)).

## Which One Do I Need?

| Your data | Use |
|---|---|
| Rows that become useless after a while (exports, temporary uploads, old notifications) | A [cleanup task](./tasks) |
| A table that grows without bound per user or organization (events, logs, messages, audit rows) | A [purge target](./purge-targets): indexed owner id, no foreign key, purged after the owner is deleted |
| A child table with a handful of rows per parent (memberships, settings, projects) | `onDelete: 'cascade'` ([Your Tables](../organizations/scoping-data#your-tables)) |
| Anything outside your database (files in storage, a record in another system) | An [after-delete hook](../organizations/deleting#after-delete-hooks), or for a deleted account an [exit hook](./exit-hooks) |

### Cascade or Purge Target?

A cascade deletes every child row in the same transaction as the parent. That is fine for a few rows and a problem for millions: the delete holds locks that block migrations and writes, and floods the database with WAL and dead rows. A purge target moves that work to the background, in batches.

A table can be both: an events table kept 90 days is a cleanup task (old rows) and a purge target (a deleted organization's rows).

## Where Things Live

| File | Owner | What |
|---|---|---|
| `apps/web/config/cleanup.config.server.ts` | You | Changes to the kit's tasks, your tasks, your purge targets |
| `apps/web/config/account-hooks.config.server.ts` | You | What happens when a user deletes their account: policies, steps, after-hooks ([Exit Hooks](./exit-hooks)) |
| `apps/web/config/cleanup.server.ts` | Kit | Binds the engine to the database and the kit's tables |
| `apps/web/crons/cleanup.ts` | Kit | The daily schedule (`0 3 * * *`); change the time here |
| `apps/web/lib/cleanup.server.ts` | Kit | Saves organization purge jobs before Better Auth's delete; `requestPurge` serves delete code you write |

The engine is `@kit/cleanup`. Its jobs, `cleanup.task` and `cleanup.purge`, run on the outbox like any other job: retried, visible in `outbox.job`, replayable ([Running and Failures](./running)).

## What Gets Logged

Task and target names, counts, durations and ids. Never the rows' contents. Fields are nested under `cleanup` (tasks) or `purge` (purges), so filter Workers Logs on those:

- `cleanup scheduled`: `{ day, created, existing, disabled }`, once per daily run.
- `cleanup task finished` / `cleanup task continues`: `{ task, day, step, deleted, batches, durationMs }`.
- `purge continues`, `purge drained, final pass scheduled`, `purge finished`: `{ ownerKind, ownerId, step, finalPass, deleted, failed, durationMs }`; `purge retries` (warn) and `purge target failed` (error, with the target) when a target fails.

---

**Next:** [Cleanup Tasks →](./tasks)
