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:
SettingDefaultDescription
interactionHistoryRetentionDays730 (2 years)How long raw interaction records are kept in the database
summaryRetentionDays2555 (7 years)How long daily summary rollups are retained
Update these via the Settings UI or the API: 
# Read current settings
curl GET /api/v1/settings

# Update retention
curl -X PUT /api/v1/settings \
  -d '{ "interactionHistoryRetentionDays": 365, "summaryRetentionDays": 1825 }'
Keep summaryRetentionDays longer than interactionHistoryRetentionDays. Summaries are much smaller and power long-term trend dashboards after raw interactions have been purged.

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

Summary Definitions

Configure how interaction data is aggregated into summaries.

Contact Policies

Suppression records managed by retention cleanup.

Infrastructure Backends

Choose the right storage backend for your interaction volume.