> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retention & Archival

> Configure data retention periods, automated cleanup, and Hive-structured exports for interaction history and summaries.

## Overview

KaireonAI stores interaction history, summaries, suppressions, and decision traces that grow continuously. The **Retention & Archival** system lets you control how long data is kept, automatically purge expired records, and export historical interactions to durable file storage before deletion.

All retention settings are configured per tenant in **Settings > Retention**.

***

## Tenant Settings

Two retention periods are configurable per organization:

| Setting                           | Default            | Description                                               |
| --------------------------------- | ------------------ | --------------------------------------------------------- |
| `interactionHistoryRetentionDays` | **730** (2 years)  | How long raw interaction records are kept in the database |
| `summaryRetentionDays`            | **2555** (7 years) | How long daily summary rollups are retained               |

Update these via the Settings UI or the API. Tenant-scoped retention windows live on the `/api/v1/tenant-settings` resource:

```bash theme={null}
# Read current tenant settings (includes retention windows)
curl GET /api/v1/tenant-settings

# Update retention
curl -X PUT /api/v1/tenant-settings \
  -d '{ "interactionHistoryRetentionDays": 365, "summaryRetentionDays": 1825 }'
```

<Tip>
  Keep `summaryRetentionDays` longer than `interactionHistoryRetentionDays`. Summaries are much smaller and power long-term trend dashboards after raw interactions have been purged.
</Tip>

### Audit-log retention

Audit-log entries follow the tenant's retention configuration for the `audit` data class. With no `audit` retention row configured, the default is **2555 days (\~7 years)** — audit trails are compliance evidence, so the fallback errs long. A retention row with `legalHold` set on the `audit` class suspends audit-log purging entirely. A 30-day minimum floor applies to any configured value.

***

## Per-class retention configuration and Legal Hold

Beyond the two tenant-settings windows above, KaireonAI has a second, finer-grained retention surface: **Settings > Retention** (backed by `/api/v1/admin/retention-configs`), which sets a retention window **per data class** and can place any class under **Legal Hold**.

| Data class      | What it covers                                                           | Purged by                                                 |
| --------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| `interactions`  | `InteractionHistory` + `InteractionSummary` rows                         | `GET /api/v1/cron/cleanup`                                |
| `decisions`     | `DecisionTrace` rows (and, under the same cutoff, `DsarExport` payloads) | `GET /api/v1/cron/cleanup`, `GET /api/v1/cron/dsar-purge` |
| `metrics`       | `MetricValue` rows (behavioral metric computations)                      | `GET /api/v1/cron/cleanup`                                |
| `audit`         | `AuditLog` rows                                                          | `GET /api/v1/cron/cleanup`                                |
| `attachments`   | `AiAttachment` rows (+ best-effort storage-blob delete)                  | `GET /api/v1/cron/dsar-purge`                             |
| `system_health` | `SystemHealthAlert` rows (`pinned` rows are always kept)                 | `GET /api/v1/cron/system-health-purge`                    |

Read and write these via the admin API (admin role required):

```bash theme={null}
# List all configured classes for the tenant
curl GET /api/v1/admin/retention-configs

# Set (or update) one class
curl -X POST /api/v1/admin/retention-configs \
  -d '{ "dataClass": "metrics", "retentionDays": 180, "legalHold": false }'
```

A class with no row configured falls back to a platform default (interactions 90d, decisions 30d, metrics 365d, audit 2555d, system\_health 90d; `attachments` has no default — it is skipped entirely until a row is configured).

### Legal Hold

Every row above has a `legalHold` boolean. When `true`, that data class is **completely exempt from automatic purging** — every cron listed in the table above skips it — regardless of `retentionDays`. There is no separate "legal hold" data class; it's a flag on each real class row.

The Settings UI's single **Legal Hold** switch applies `legalHold` to every class it manages in one save (fans the same boolean out across `interactions`, `decisions`, `metrics`, `audit`, `attachments`, and `system_health`), so flipping it on suspends purging platform-wide for that tenant. Placing a hold on an individual class via the API directly (e.g. only `decisions`) suspends purging for just that class.

<Warning>
  A retention-config save only reports success once **every** class POST has actually succeeded (HTTP 200). If any class rejects the request — e.g. an out-of-range `retentionDays` — the save is reported as failed and no partial state should be assumed.
</Warning>

***

## Automated Cleanup

The cleanup cron purges expired data on a schedule. Trigger it via:

```
GET /api/v1/cron/cleanup
```

**What it does:**

1. **Expired suppressions** — Deletes suppression records where `expiresAt < now()`. This keeps the suppression table lean for fast decision-time reads.
2. **Old daily summaries** — Deletes daily summary rows older than `summaryRetentionDays`.
3. **Old interaction history** — Deletes interaction records older than `interactionHistoryRetentionDays` (run the export cron first if you need to preserve them).
4. **Old decision traces** — Deletes `DecisionTrace` rows past the tenant's `decisions` retention class.
5. **Old metrics** — Deletes `MetricValue` rows past the tenant's `metrics` retention class.

Each of steps 2–5 is skipped for a tenant whose corresponding data class has `legalHold` set — see [Legal Hold](#legal-hold) above.

<Warning>
  Always run the export cron **before** cleanup if you need to retain interaction data beyond the retention window. Once purged, records cannot be recovered from the database.
</Warning>

***

## Interaction History Export

The export cron writes interaction history to **Hive-partitioned files** for long-term storage and analytics:

```
GET /api/v1/cron/export-interactions
```

### Hive Directory Structure

Exported files follow a date-partitioned layout compatible with Spark, Athena, Trino, and other query engines:

```
exports/{tenantId}/interaction_history/
  year=2026/
    month=03/
      day=25/
        interactions_2026-03-25_001.jsonl
      day=26/
        interactions_2026-03-26_001.jsonl
```

Each file is a newline-delimited JSON (JSONL) file containing the full interaction record including customer ID, offer, creative, channel, outcome, timestamps, and attribution data.

<Tip>
  Point your data lake (S3, GCS, Azure Blob) at the `exports/` directory and register it as a Hive-partitioned external table for ad-hoc queries across years of interaction data.
</Tip>

***

## GDPR & Right to Erasure

KaireonAI supports configurable retention to help meet data protection requirements:

* **Right to erasure:** Use the GDPR erasure API at `POST /api/v1/gdpr/erasure` with body `{ "customerId": "..." }` (admin role required) to atomically delete all interaction history, summaries, suppressions, decision traces, and attribution records for a customer. Returns per-table delete counts for audit.
* **Configurable per org:** Each tenant can set retention periods appropriate to their regulatory environment. Financial services may require 7-year retention; consumer apps may set 1 year.
* **Audit trail:** Cleanup and export operations are logged in the audit log with the number of records affected, timestamps, and the initiating user or cron trigger.

<Note>
  The erasure endpoint performs a hard delete across all tables in a single transaction. Exported Hive files must be purged separately from your file storage if a customer exercises their right to erasure.
</Note>

***

## Related

<CardGroup cols={3}>
  <Card title="Behavioral Metrics" icon="chart-bar" href="/studio/behavioral-metrics">
    Configure computed aggregations over interaction history, materialized as MetricValue rows.
  </Card>

  <Card title="Contact Policies" icon="shield" href="/decisioning/contact-policies">
    Suppression records managed by retention cleanup.
  </Card>

  <Card title="Infrastructure Backends" icon="server" href="/self-host/deploy/infrastructure-backends">
    Choose the right storage backend for your interaction volume.
  </Card>
</CardGroup>