Skip to content
bucker

Data retention

How long Bucker keeps each kind of data, how it leaves, and who may change that. This page is the reference for GET /orgs/{org}/retention/windows, the data_retention_get and retention_change_propose MCP tools, and the Retention windows card under Settings, Compliance.

What you can read

GET /orgs/{org}/retention/windows (and data_retention_get, with the same model) lists every stream that holds tenant data:

Field Meaning
effectiveDays The window enforced now, after clamping to the plan.
source Where it comes from: plan, org_override, project_override, setting (the stream's own column), project_setting, or fixed.
ceilingDays What the plan keeps at most. A window above it is clamped when read, so a downgrade tightens at once and an upgrade restores the longer window.
mechanism How the rows leave: partition_drop (a whole day-partition, no row DELETE), row_delete, object_then_row_delete (the stored object first, then the row that names it), archive_then_partition_drop.
sweep When the sweep that owns the stream last ran, and whether it is overdue (two intervals).
receipt The newest signed deletion receipt, with its signature verified at read.
overridable Whether a window override is read by this stream's sweep.

The streams are the four per-organization ones (audit_logs, spans, log_records, replay_segments), class-partitioned metric_points, event hot and cold storage, the query log, the ingest queue, attachments, and every derived stream (rollups, outcome ledgers, change events). A new stream in a retention registry fails the census test until it is listed.

Receipts

metric_points sweeps sign one receipt per organization per partition or row-delete batch: a DSSE envelope over an in-toto statement of kind deletion_sweep, signed with the Proof Ledger key. The other sweeps record their counts in the audit log and lastEnforcedAt; they say so (receiptNote) rather than showing a receipt that does not exist. There are no legal holds in this release, and the read says that too.

Rows written before a change

A metric point carries the retention class it was written with. After a window is lengthened, rows already stored keep the shorter class and drop on its schedule; only rows written afterwards use the new window. No read claims the new window for the old rows. A shortening is the opposite: rows stored under a longer class are deleted once, with a receipt, so that no stated window is exceeded.

Changing a window

Five streams read an override: the four per-organization streams (organization level) and metric_points (organization or project level, in retention classes of 3, 7, 14, 30, 90, 180 or 365 days). The change is read from its effect, never from its name: a longer effective window is a lengthening, a shorter one is a shortening.

Lengthening: retention_window.update

POST /orgs/{org}/retention/changes or the retention_change_propose tool. The act is SENSITIVE and carries the registry's ask floor, so it is always asked: the first call returns the plan and its digest with an open approval request; a person approves exactly that plan; the retry (with the request id, or the same inputResponses over MCP) applies it against the revision it was asked on and signs a receipt. No policy row and no review mode applies it without a person. The window must be inside the plan ceiling.

The tool is held until the SG-059 security review (it needs usage:write, outside today's token ceiling).

Shortening: retention_window.erase

POST /orgs/{org}/retention/erase, a person's act on their own session: never an agent, an OAuth client or a service principal, and never the plain PUT /orgs/{org}/compliance/retention, which now refuses every shortening and points here. Shortening is irreversible and has no stored inverse.

  • Below the line (under 30 days of window removed and under 10 % of the stream's rows): the person files, confirms with a step-up, and it applies at once.
  • Above either: dual control. The request waits out a 72-hour hold; every owner is told; any eligible human may reject during it; two approvers outside the requester's chain vote with their own step-ups (an organization too small for that waives the quorum and keeps the hold); and the requester confirms with a fresh step-up. The sweeper then applies it. An unmeasured row share counts as above.

The rows past the new window leave at the next sweep. Before filing, ask for the preview: GET /orgs/{org}/retention/windows?include=change_preview&stream=spans&days=30 returns the rows (and, for replay, objects) that would leave per day, the alert rules that look back past the new window, the shared views over the stream, the legal holds (none) and, for a lengthening, the storage it adds. The estimates come from the ingest ledger's accepted counts (before sampling, so an upper bound) and, for audit rows, an exact count. The accepted counts are a rollup: while it is not live and fresh, or when the removed days predate its first count for an organization older than that, the share is reported as not measured (rowShare: null) and the shortening is above the line. Alert rules and views in projects you cannot read are counted in a warning, never named.

Metric points are deleted once for the whole organization. A shortening is refused while a project keeps its own longer metric-point window, and a project-level shortening is refused while that project holds rows under a longer class.

Audit

Applying a change writes retention.window.set under the organization, beside the engine's operation.applied and the signed operation_applied receipt. The operator console's lifecycle retention panel lists each organization's overrides and newest receipts (names, days and counts, never rows).