# Data retention

What Kaabist stores about your work, where it lives, when it is deleted, and how to ask for everything to be erased.

Everything Kaabist keeps about your work lives in one of three places: the transactional database, object storage, and the append-only ledger and audit log. This page says what goes where and for how long, so you know what you can read back later, what you cannot, and what an erasure request removes.

## When to use it

Read this page before you automate a site whose pages hold personal or confidential data, when you answer a data-protection questionnaire about Kaabist, when you need to know whether last quarter's snapshots are still there, or when you want your organisation's data erased. The customer-facing summary of how that data is protected is in [Security and data](https://docs.kaab.ist/guides/security-and-data).

## At a glance

| What | Where | Kept for |
|---|---|---|
| Jobs: inputs (encrypted), result, warnings, metadata | database | 13 months; results stay readable whatever your credit balance |
| A job's timeline and step records | database | 13 months |
| Test-mode job results | database | 24 hours |
| Page snapshots, screenshots, downloaded artifacts, attention bundles | object storage | your plan's retention: 7, 30 or 90 days ([Plans and pricing](https://docs.kaab.ist/reference/plans)) |
| Ground-truth snapshots of a program version | object storage | as long as the version is in use |
| A builder draft's own timeline | object storage | 7 days |
| Usage statistics per job (counts, durations, credits; never page content) | analytics store | 13 months |
| Credit ledger | database | never deleted |
| Audit log | database | never deleted |
| Live view frames | nowhere | never stored |

## Jobs and their timeline

A job carries its inputs, its result, the tier it ran at and the credits it cost. Every status change appends a row to its timeline, and each step records its own attempt, so a retry that succeeded on the second try still shows the first one. Timelines and step records are kept for **13 months**, after which the month they belong to is dropped as a whole.

Running out of credits never makes a result unreadable: reads keep working when the balance is zero.

## Snapshots and screenshots

Page snapshots, screenshots, downloaded files and attention bundles live in object storage under a key that starts with your organisation, so nothing is shared between customers by accident. Retention follows your plan: 7, 30 or 90 days, see [Plans and pricing](https://docs.kaab.ist/reference/plans). The snapshots a program's fields were confirmed against, its ground truth, are exempt: they are the reference healing works from, and they live as long as the program version is in use. [Snapshots](https://docs.kaab.ist/concepts/snapshots) describes what one of them holds and what it never holds.

## Secrets

Session storage state, stored passwords, secret inputs, webhook signing secrets and bring-your-own provider credentials are encrypted before they are written, with a key per organisation that is itself wrapped by a key Kaabist never stores next to the data. No plaintext secret is written to the database, to a snapshot, to a screenshot, to a webhook or to a log line. API keys are stored only as a hash: the key itself is shown once, when it is created.

## Credits and the audit log

The credit ledger is append-only. A reservation, a settlement, a refund and an expiry are each their own entry, and the balance is derived from them. Nothing rewrites history, so an invoice can always be traced back to the jobs behind it. The audit log records every approval, takeover, key change, role change, session change, billing change and data-deletion request, with who did it, from which address and with which browser. Ledger entries and the audit log are never deleted.

## Getting your data out

An owner or admin can ask for everything at once: **Export data** under **Organisation settings** in the panel. It needs two-factor authentication on your account and a sign-in in the last fifteen minutes. Kaabist builds a zip and e-mails you a link that works for seven days. The archive holds your programs and every version of them, your sessions' names, origins and validity (never their stored state), the last ninety days of jobs with their results, the credit ledger and the audit log as CSV, and your schedules and webhook endpoints. It never holds a key, a signing secret, a provider credential or a stored input. One export is built at a time; asking again while one is being built returns that one.

Anything else you read back through the API while it is retained: `GET /v1/jobs` and `GET /v1/jobs/{id}` for results, `GET /v1/jobs/{id}/steps` and `GET /v1/jobs/{id}/snapshot` for steps and pages, `GET /v1/ledger` and `GET /v1/usage` for credits. The panel's **Credits** page exports the ledger rows it has loaded as CSV.

## Erasing your data

An admin, or an `admin` API key, asks for everything to be erased:

```http
POST /v1/org/data-deletion
```

```json
{ "confirm": "acme-pricing" }
```

`confirm` must be your organisation's slug, typed back. The answer is `202`:

```json
{ "id": "exp_01J…", "scheduled_for": "2026-10-08T09:00:00Z" }
```

The request is carried out within minutes, and always within 24 hours, in this order:

1. **Stopped.** The organisation is disabled, its API keys revoked, its schedules paused, its unfinished jobs canceled and its live sessions ended.
2. **Files.** Every snapshot, screenshot, result, downloaded file, attention bundle, asset and export of the organisation is deleted from object storage.
3. **Records.** Programs and their versions, sessions (state and refresh inputs), provider settings, webhooks and their deliveries, schedules, members, invitations and API keys are deleted. Job records are emptied (inputs, results, warnings, errors, everything but the id, the times and the cost) and removed thirty days later.
4. **What stays.** The credit ledger and payment records, because tax and commercial law require them; the audit log, because it is the security record, with every person in it replaced by a pseudonym that cannot be traced back; the usage statistics, under a random token that no longer names your organisation.
5. **Confirmation.** The person who asked (or, when an API key asked, the owners) receives an e-mail when it is done.

Backups are not edited by an erasure: data already copied into a backup stays there until the backup expires, within 35 days.

The request is recorded with what you typed, and only one can be outstanding at a time: asking again before it is done returns the first request rather than starting a second.

In the panel, an owner can instead use **Delete organisation** under **Organisation settings**: it asks for the organisation's name and carries out the same deletion.

## Worked example

An organisation on the developer plan (30 days' retention) runs a job against `https://shop.example.com/p/1` on 1 October.

- Until 31 October, `GET /v1/jobs/{id}/snapshot?step=steps[1]` returns the stored page, and the panel's **Open the stored page** shows it.
- After that, the snapshot is gone, but `GET /v1/jobs/{id}` still returns the job and its `data`, and `GET /v1/jobs/{id}/steps` the step records, until the job's month is dropped thirteen months later.
- The job's ledger entries (its reservation, settlement and release) remain for good.
- If the organisation asks for erasure on 5 October with `{ "confirm": "<its slug>" }`, the job, its result and its snapshots are destroyed within 24 hours; its ledger entries and the audit row for the request remain.

## Pitfalls

- **Plan retention applies to stored pages.** If you need a page for longer, read what you need from it while it exists.
- **A downgrade shortens retention.** Snapshots are kept for the plan's period; check [Plans and pricing](https://docs.kaab.ist/reference/plans) before you change plan.
- **Erasure cannot be undone.** And it removes sessions too, so scheduled programs that rely on them fail until you sign in again.
- **Do not put personal data in tags or program names.** They are part of the job record and are kept with it.
- **Test mode is not a sandbox for real data.** Test jobs run for real against real sites; only their results expire sooner.

## Reference

- [Request data deletion](https://docs.kaab.ist/reference/api/org/request-data-deletion)
- [Get a job](https://docs.kaab.ist/reference/api/jobs/get-job), [list a job's steps](https://docs.kaab.ist/reference/api/jobs/list-job-steps), [list ledger entries](https://docs.kaab.ist/reference/api/ledger/list-ledger-entries)
- [Plans and pricing](https://docs.kaab.ist/reference/plans)
- [Security and data](https://docs.kaab.ist/guides/security-and-data)