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 Core API enforces them in the background and mirrors effective settings in each session’s metadata.retentionStatus (without changing public session DTO shapes).

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 Core API stamps retentionStatus into MetadataJson:

{
  "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

RetentionHostedService runs in the Core API (default every 5 minutes; override with platform key system.retention.tick_minutes). Each tick processes up to 50 due sessions.

Manual test endpoints (privileged)

Requires Privileged or System request privilege (same as static refresh triggers).

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 via the Core API template upgrade flow when you adopt retention on a running cluster.

Related topics

• Session Templates
• Sessions
• Statics
• Data sovereignty