Retaining Events

A retention policy is the only way events leave a project short of deleting the project itself. Each project has exactly one. Before going to production, you almost certainly want to set one — the default for new projects is 30 days.

Why retention matters

Two reasons projects need a retention policy:

• Regulatory — SOC 2, HIPAA, PCI, and many customer contracts cap how long you may keep activity logs containing personal data. Often 90 days; sometimes 1 year; sometimes 7.
• Cost — events are cheap to store but not free. Indefinite retention adds up.

Configuration

In the dashboard: project → Settings → Event retention. Pick a retention period from the dropdown and click Save.

Lengthening retention (e.g. 30 → 90 days) only affects events newly written from that point forward; events older than the previous policy that have already been purged are gone.

Shortening retention (e.g. 365 → 90 days) takes effect on the next nightly purge — events older than the new cutoff disappear within 24 hours.

How purging works

A background worker runs once per day per project that has a retention policy. It deletes every event whose occurred_at is older than now - retention_days. The purge is irreversible — there is no soft-delete, no trash, no recovery.

The settings panel shows a Last purged line so you can confirm the worker has run since the policy was set.

Purge now

You can trigger an immediate purge against a project's policy by clicking Purge now in the Event retention panel.

The button is disabled until there's something purgeable — when Last purged: Never and no events exist, there's nothing for the worker to do.

The "purge now" endpoint respects the project's retention_days — it doesn't accept an ad-hoc cutoff. If you need to delete a specific event, delete the project; if you need to delete a specific kind of event, redact it client-side before recording.