Skip to main content

​
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: Update these via the Settings UI or the API. Tenant-scoped retention windows live on the /api/v1/tenant-settings resource:
Keep summaryRetentionDays longer than interactionHistoryRetentionDays. Summaries are much smaller and power long-term trend dashboards after raw interactions have been purged.

​
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.
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. Read and write these via the admin API (admin role required):
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). 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.
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.

​
Automated Cleanup

The cleanup cron purges expired data on a schedule. Trigger it via:
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 above.
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.

​
Interaction History Export

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

​
Hive Directory Structure

Exported files follow a date-partitioned layout compatible with Spark, Athena, Trino, and other query engines:
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.
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.

​
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.
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.

Behavioral Metrics

Configure computed aggregations over interaction history, materialized as MetricValue rows.

Contact Policies

Suppression records managed by retention cleanup.

Infrastructure Backends

Choose the right storage backend for your interaction volume.