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