Session retention

Session retention controls how long Sessions keep node outputs and when whole sessions are removed. Policies are declared on the Session Template configuration JSON. The platform enforces them in the background and records effective settings in each session’s metadata.retentionStatus (visible through integrator APIs where exposed).

Three modes

Idle period is measured from last activity: the newest NodeOutput.CreatedAt in the session. If the session has no outputs yet, Session.CreatedAt is used.

Threshold uses Kubernetes-style durations, for example 1s, 30m, 1d, or 1d 12h.

Template configuration

Authoritative policy lives in the session template root configuration:

{
  "retentionPolicy": {
    "mode": "ArchiveByAge",
    "threshold": "3d"
  }
}

When a session is created, the platform stamps retentionStatus into session metadata:

{
  "retentionStatus": {
    "mode": "ArchiveByAge",
    "threshold": "3d",
    "lastActivityAtUtc": "2026-05-18T12:00:00.000Z",
    "lastEnforcedAtUtc": null
  }
}

• lastActivityAtUtc: Updated when enforcement runs and on create.
• lastEnforcedAtUtc: Set after a successful archive or delete sweep for that session.

Omit retentionPolicy or set mode to KeepAll for legacy behaviour (no automatic cleanup).

Per-node archive opt-out

Node instances copy defaultConfiguration from the template. Add retention.skipArchive to keep all outputs for that node during ArchiveByAge (the node is still removed on DeleteByAge):

{
  "retention": {
    "skipArchive": true
  }
}

Use this on dashboard rollup nodes (for example cluster-usage-history, dataservice envelope, Next dimension) while allowing high-volume upstream nodes (for example cluster-report) to trim to the latest snapshot only.

Input node templates (NodeType.Input, such as input-node) are never archived; ingest and heatx history stay intact until the whole session is deleted.

What archive deletes

For each eligible non-input node:

1. Keep CurrentOutput (or the newest output if unset).
2. Remove other NodeOutput rows.
3. Delete S3 objects when no remaining output references the same bucket + object_name (shared heatx keys use reference counting).
4. Repoint SessionDimension and RunnerTask.LastRunnerOutput references to the kept output where needed.

Non-heatx and heatx-backed outputs in the managed bucket heat-{sessionId} follow the same rules.

What delete removes

DeleteByAge clears FK blockers, deletes all objects in the session S3 bucket, then removes the session row (cascade removes node instances and outputs). Sessions that back a Static instance are skipped by the automatic sweep; use a privileged force delete only for testing.

Background enforcement

The platform runs retention on a schedule (default about every 5 minutes). Operators can tune the interval with system.retention.tick_minutes in Platform configuration.

Statics and Resource Monitor

High-frequency static refresh (for example Resource Monitor at one minute) can produce thousands of cluster-report outputs per backing session. Combine:

• Backing-session rotation on the static definition (backingSessionRotation.period, e.g. 24h) to start a new session each period (see Statics).
• ArchiveByAge on the template (shipped heat-system-resource-monitor-next uses 7d), with skipArchive on rollup and dashboard nodes, to trim outputs inside the current backing session.

Upgrade an existing static definition to a new template revision through your deployment team’s template upgrade workflow when you adopt retention on a running cluster.

Related topics

• Session Templates
• Sessions
• Statics
• Data sovereignty