Langfuse data retention policies: when a self-hosted instance needs one
Retention in Langfuse is set per project as a window in days, with a minimum of 3 days, and a self-hosted instance needs the Enterprise Edition license key to use it. Without a policy, a self-hosted instance keeps event data indefinitely. That default conflicts with the data-minimization rules many organizations apply to personal data, including data that appears in prompts, completions and metadata. If your internal standard sets a maximum age for operational data, decide on the window before the instance receives production traffic, so the earliest records are covered as well.
Three groups own this decision. Security teams usually hold the data-handling standard and decide which categories of event data may be kept and for how long. Privacy teams answer questions from data subjects and auditors about where personal data is stored and when it is deleted. Platform owners run the deployment, hold the license key and must confirm that the nightly cleanup behaves as the policy states. Ask each group to sign off on the same window before it is configured, because the setting is only as accurate as the agreement behind it.
Start with four checks. First, list which Langfuse projects will receive traces and whether any of them will carry personal or sensitive data. Second, find the period your standard allows for LLM telemetry and whether any project needs a longer history for debugging, evaluation or a legal hold. Third, confirm whether teams rely on older traces for regression comparisons, since a short window removes them permanently. Fourth, decide how archiving will work for data that must be kept longer than the window allows. Deleted data cannot be recovered, so these answers come before the first deletion runs.
Retention is one of several governance features in the Langfuse features group, alongside audit logs, role-based access, data masking, encryption and provisioning. Several of these also need the Enterprise license key on a self-hosted instance, including project-level roles, audit logs and server-side data masking. Confirm with Langfuse which features your license covers before you finalize the design, because the license is a cost component of the deployment and the public self-hosted pricing page lists a custom-priced Self-Hosted Enterprise plan, with a quote based on your written scope.
Retention configuration options and when each one fits
This table compares the three ways to set a retention window in self-hosted Langfuse, along with the scope each one reaches. Read each row for the setup method, whether it suits one project or many, and the caution that applies. Langfuse has no organization-level retention policy, so every project needs its own window whichever method you use.
| Method | Scope it reaches | When it fits | Main caution |
|---|---|---|---|
| Project settings in the UI | The one project being edited, set by a user with admin rights in that project | A single project, or a small number of projects where manual changes are acceptable | Minimum window is 3 days. Projects you forget keep data indefinitely, so track each one. |
| Organization Management API | Each project addressed in the calls, so a script can cover the whole organization | Many projects, or provisioning pipelines that create projects automatically | Confirm endpoints, authentication and request format in the API reference for your version, then verify each project. |
| LANGFUSE_INIT_PROJECT_RETENTION | Only the project created when the instance starts | First project on a new instance, in headless or infrastructure-as-code setups | Covers one project only. Set the window for every later project through the UI or the API. |
| Organization-wide retention policy | Not available in Langfuse | Not applicable | Each project needs its own window, so keep a written list of project windows. |
| Enterprise license key | Applies to all three methods on self-hosted instances | Any self-hosted deployment that needs retention | Without the key, retention settings are not available. Confirm the license setup before planning deletions. |
What retention leaves behind: audit logs, dataset items and saved media
Project retention is narrower than many teams expect. The nightly cleanup removes traces, observations, scores and media assets older than the retention window, but it does not delete audit logs or dataset items. A deployment that sets a 30-day window still holds records of who changed retention and curated datasets that may contain inputs and outputs from months earlier. Treat the retention setting as a rule for one category of data, not as a statement about the whole instance. Your data inventory should say this explicitly, so that the retention setting is never mistaken for proof that personal data has been removed everywhere.
Media attached to saved dataset items is also excluded from retention deletion. Dataset items are the examples your team saves for evaluations and experiments, and any image, audio file or document attached to one stays in place after the nightly job removes the traces it originally came from. Confirm this in your own environment before relying on it. Create a test project, add a dataset item with an attachment, create a trace older than the window, run the cleanup on a non-production instance, and then record which trace data, which media and which dataset content remain in the UI and through the API.
These exclusions change compliance scoping. Your data inventory should list audit logs, dataset items and dataset media as separate rows from trace data, each with the store that holds it, its owner, its retention behavior and the method used to delete it. Trace data follows an age rule that the nightly job enforces. These categories do not follow that rule, so a single retention figure cannot describe them. When an auditor asks where personal data is kept, the answer should include these rows. Map each row to the control in your framework that governs it, and describe that control in your own words, using the framework's control identifiers rather than copied text.
The privacy owner should decide whether dataset content that contains personal data needs its own handling. Datasets are often built by copying production traces, which means names, contact details or customer messages can end up in expected outputs, input fields or attached files. Retention will not remove those items on its own. The decision is whether to prohibit personal data in datasets, require masking before an item is saved, set a periodic review of dataset content, or delete items on a documented schedule. Record the decision, the people authorized to delete dataset items, and the steps they follow, and confirm that the role used for those deletions is held only by people who need it.
Before you rely on any of this, confirm the exact behavior of each data type in the Langfuse version you run. Retention and dataset handling can change between releases, and an upgrade is a good moment to repeat the test. Check the Langfuse data retention documentation for your version, run the test described above on a non-production instance, and keep the version number and results with your compliance evidence. If an auditor will rely on a specific behavior, ask your Langfuse contact to confirm it in writing and note the date of that confirmation in your inventory.
Applying one retention window across many projects
This sequence gives one retention window to every project in a self-hosted Langfuse instance and leaves a record that the window is in force. It shows the order of work and can be adjusted to your deployment and change control. Each step closes with a check you can show a reviewer or auditor.
Confirm the Enterprise license key is active
The platform owner confirms that the instance runs with an active Enterprise license key, because data retention policies are an Enterprise feature for self-hosted Langfuse and cannot be set without one. Check the license status against the license key documentation and your instance administration view, then record the key's expiry date and the Langfuse version in production. The step is done when a project's retention setting can be opened and changed on this instance.
Set the window for each project
The data owner and the platform owner decide a retention window in days for each project, based on the data classification of what its traces contain. For example, an illustrative project that handles customer prompts might take a shorter window than an internal evaluation project that uses synthetic inputs. Record each window beside the project name and its classification in a decision sheet, and note that the minimum window is 3 days. The step is done when every project has a written window and a named approver.
Set the startup project window at initialization
If the deployment creates a project at startup through headless initialization, set LANGFUSE_INIT_PROJECT_RETENTION in the deployment configuration to the window decided for that project before the first start. This variable applies only to the project created at startup, so every other project still needs its own setting. The check is that the startup project shows the expected window after first boot and that the configured value matches the decision sheet. Keep the configuration under version control so the value can be reviewed.
Apply the window to every other project
Apply each remaining window through the UI or the Organization Management API, which requires an Enterprise license key. The UI suits a small number of projects, while a script that calls the API suits a larger set, with the project list taken from the API so that no project is missed. Work from the decision sheet and keep each change traceable to the person who made it. The step is done when every project has been changed and none is left without a policy.
Confirm new projects receive the intended window
There is no organization-level retention policy, so a project created after this rollout starts with no window and stores event data indefinitely until someone sets one. Create a test project in a non-production setting, confirm it has no window, apply the approved value, and add that step to the procedure for creating projects. Check that the procedure runs before any production traces are sent to a new project. The step is done when the test project reads back the intended window and the procedure names who sets it.
Verify each project setting by read-back
Read the retention setting back for every project, using a report or the Organization Management API, and compare each value with the decision sheet. Look for projects with a missing value, a value that differs from the sheet, and projects that appear in the API but not in the sheet. Resolve each mismatch by correcting the setting and rerunning the read-back for that project. The step is done when the comparison shows no open differences and the output is saved with the date it was run.
Record settings and owners in change log
Add one change log entry per project containing the project name, the window in days, the classification it was based on, the named owner, the person who applied the setting, and the date. Note that project retention does not delete audit logs or dataset items, so the entry should state which data the window covers. Review the log when classifications change or when a project is retired. The step is done when every project has an entry with an owner and the entries match the read-back output from the previous step.
Archiving data before retention deletes it
Deletion under a retention window is final. Each night, Langfuse removes traces, observations, scores and media assets older than the configured period, and deleted data cannot be recovered. If a team, an auditor or a model evaluation will need part of that history after the window closes, the copy has to exist before the cleanup runs. Build archiving into the retention design and schedule it ahead of the first deletion. The age check uses the trace timestamp, observation start_time, score timestamp and media created_at, so confirm how the cutoff applies to each record type before you choose an archive date.
Scheduled export to blob storage is the archiving path. The export copies observations and scores out of the instance into storage you control, where the data stays available after the nightly cleanup removes it from Langfuse. Backup and restore serves a different purpose. It protects the platform against loss of a data store, so it is the path for disaster recovery. An export is not a restore path for a live instance: you cannot reload exported files into Langfuse to bring back a project as it was. Plan both paths separately, and confirm with your team which of them covers each data type you care about.
Deciding what to archive is a business decision before it is a technical one. List the projects, record types and time ranges that someone will need later, such as production traces used for incident review or evaluation runs used for model comparisons. Note that retention does not delete audit logs or dataset items, and media attached to saved dataset items is excluded from retention deletion, so those records may not need an archive for retention reasons. Keep the list short enough that the archive stays manageable, and review it whenever a project's purpose changes.
Name an approver for each archive scope before the window changes. The project owner usually confirms the business need, and the privacy or legal contact should confirm whether the archived data contains personal data that the archive is allowed to keep for longer. Record the decision with the window length, the scope, the approver and the date, and keep that record with your retention settings. Ask any implementation partner to show how the approval step is written into the runbook, so the approval is an explicit gate rather than an informal understanding.
Once live data expires, the archive may be the only copy of that history, so its access controls need to be tighter than the access to the Langfuse interface. Restrict bucket access to named service identities and a small group of reviewers, enable encryption and read logging, and confirm whether your storage platform supports retention locks. Project roles in the Langfuse interface do not govern bucket permissions, and project-level RBAC roles and retention policies require an Enterprise license key on a self-hosted instance. Review who can read the archive on a fixed schedule, and test that an authorized reviewer can open a sample file before the first deletion.
Security and operational risks of retention deletion
Retention deletion removes data on a schedule and cannot be reversed, so the settings that control it need the same care as any production change. The cards below cover window length, coverage of new projects, who may change the window and the record of those changes. Audit logs and dataset items sit outside the nightly job, but backups that protect deleted traces remain your responsibility.
Window shorter than investigations
Langfuse deletes traces, observations, scores and media once they pass the retention window, judged by trace timestamp, observation start_time, score timestamp and media created_at. A window near the 3-day minimum can expire evidence before a slow security review or a customer dispute reaches it. Control: agree the window with incident response and legal owners, measure it against your longest review cycle, and ask reviewers how far back they need to query before you set it.
New projects without a window
Langfuse has no organization-level retention policy, so each project needs its own window set in the UI or through the Organization Management API. A project created later, or the startup project without LANGFUSE_INIT_PROJECT_RETENTION set, keeps event data indefinitely on a self-hosted instance. Control: make the window part of the project creation checklist, and run a recurring check that lists every project's retention setting against your standard.
Who can change the window
Retention is an Enterprise feature that is governed by project roles. Any user who can edit a project's retention setting can shorten it, and the next nightly run will delete data that the longer window would have kept. Control: limit the change to a small named group, and confirm in the Langfuse role documentation for your version which minimum project role can edit retention before you assign roles.
Audit trail for window changes
Project retention does not delete audit logs, so the history of past activity survives a shorter window. You need the record of who changed a window and when, so confirm that audit logs capture changes to retention settings with the actor and timestamp in your Langfuse version. Control: forward or export those entries to your central log platform on a schedule, so the change history stays available outside Langfuse.
Nightly deletion cannot be undone
The nightly job removes expired data, and deleted data cannot be recovered from Langfuse. A mistaken window, a wrong project or a bad timestamp can remove history with no rollback inside the application. Control: schedule backups of ClickHouse and PostgreSQL that cover the full retention period, archive any data you must keep before it expires, and test a restore before you depend on it.
What buyers ask before setting retention on self-hosted Langfuse
Does setting data retention in self-hosted Langfuse require a paid license?
Yes. Data retention policies require an Enterprise license key on a self-hosted instance. Langfuse's core tracing, prompt management and evaluation features are available in the MIT-licensed open source version, but its repository places the enterprise code in separate directories under a separate license, and retention is one of the features that depends on it. Without a policy, a self-hosted instance keeps event data indefinitely, so teams that must delete data on a schedule need the key. Langfuse's Self-Hosted Enterprise plan is custom-priced, so ask Langfuse directly for its current terms, and confirm whether the license covers every instance you run, including staging and test environments.
What drives the cost and effort of a retention rollout?
The number of projects drives most of the work. Retention is set per project, and there is no organization-level policy, so each project needs its own window in the UI or through the Organization Management API. Other drivers include how many different windows your data owners require, how much personal data each project holds, how much testing you run in a non-production copy, and how many approvals you need to record. Costs fall into two groups: an implementation partner is paid for the scoped work under a written quote, and your team pays for its own staff time. The Enterprise license is a separate recurring cost. Ask for a quote that lists the projects covered, the windows, the test steps, the handover and any ongoing work.
How long does a retention rollout take in practice?
Duration depends on project count and scope, so no single figure applies across deployments. An instance with a few projects and one agreed window can be configured quickly. An instance with many projects, several windows, or API-driven changes takes longer because each setting needs verification. Ask for a timeline in the written scope that covers license key installation, configuration for each project, a first test run in a non-production copy, and sign-off by the data owners. Include time for the first nightly run after a window is set, because that is when deletion happens and when you confirm the results.
What does a retention rollout need from our team before it starts?
The work depends on access and decisions more than on engineering effort. Prepare the following before the first configuration change:
- An Enterprise license key for the instance
- Admin access to the Langfuse UI, plus API access if you plan to use the Organization Management API
- A current list of projects, with a named owner for each
- Retention windows approved by the data owners, and by privacy or legal reviewers where personal data is involved
- A non-production copy of the instance for testing
- Verified backups of the production data stores, because deleted data cannot be recovered
- A change window that allows the first nightly run to be checked the next morning
Can our platform team set retention on self-hosted Langfuse without a partner?
Yes, if the team has the license key, admin access and time for the work. The setting itself is simple for each project. The harder parts are building the project inventory, getting window decisions approved, confirming which timestamps govern deletion, testing, and keeping evidence. Retention judges traces by trace timestamp, observations by start_time, scores by their timestamp, and media by created_at, so the team needs to understand that before it sets a window. A partner adds value when you want a fixed scope, a documented result and handover, or support across many projects on a short timeline. Decide based on your internal capacity and the number of projects you need to cover.
Can we archive traces before the retention window expires?
Yes, but retention itself does not archive anything. Once the nightly job runs, traces, observations, scores and media older than the window are deleted and cannot be recovered. If you need older data for audit, analytics or long-term retention, export or back it up before it expires. A scheduled export to blob storage and a database backup serve different purposes, so confirm that the approach you choose keeps the fields and history you need. Audit logs and dataset items are not deleted by project retention, and media attached to saved dataset items is excluded, so those records need no archive for this purpose. Test the archive and restore steps in a non-production copy before you rely on them.
Can we shorten or change a retention window after setting it?
You can change a window, but the effect of a shorter window is immediate at the next run. A shorter window makes the nightly job delete every qualifying record older than the new period, and that data cannot be recovered. Langfuse sets a minimum of 3 days per project. Lengthening a window does not restore data that has already been deleted. Before you change a window, confirm the new period with the data owners, record the approval, export anything you need to keep, and test the change in a non-production copy so you know what the next run will remove.
Limits to confirm in your environment before you set a window
These items set the boundaries of what a retention window can do in self-hosted Langfuse. Each one is a question to answer with Langfuse or in your own environment before a window goes live. Treat them as acceptance checks for the policy design and record each answer with the owner who signed it off.
Three-day minimum window
Langfuse accepts a retention value of at least 3 days for each project. Confirm that this floor fits your legal hold, incident review and analytics needs, because a shorter requirement cannot be met inside Langfuse. Ask the vendor whether the minimum changes in the version you plan to run, and check that version's release notes before you write the policy into runbooks.
Enterprise license key requirement
Data retention policies are an Enterprise license feature for self-hosted Langfuse. Without a policy in place, event data is stored indefinitely, so the license decision directly controls how long personal data in traces persists. Confirm with Langfuse which key tier covers your instance, who holds the key in your secrets store, and how a lapsed or replaced key affects retention jobs already scheduled.
No organization-level policy
Langfuse has no organization-level retention setting. Each project needs its own window, set in the UI or through the Organization Management API, and LANGFUSE_INIT_PROJECT_RETENTION covers only the project created at startup. Confirm how you will catch projects created later and whether your provisioning code sets the window on every new project.
Excluded data types
Project retention leaves audit logs and dataset items in place, and media attached to saved dataset items is excluded from deletion. Confirm that your privacy and compliance scope accepts these exclusions, since personal data inside dataset items or audit records will persist beyond the window. Ask Langfuse for the exact objects covered, then verify with a test project and plan separate handling for those stores.
Irreversible deletion and existing data
The nightly job permanently deletes traces, observations, scores and media older than the window, and deleted data cannot be recovered. Confirm whether data stored before the policy was applied is removed on the next run, since a project with years of history may lose far more than expected. Take a verified backup before the first run, because an export alone may not restore data, and record the decision for auditors.
Nightly job load and storage headroom
The nightly job judges age by trace timestamp, observation start time, score timestamp and media creation time, and it runs against your ClickHouse cluster. Confirm how long a run takes at your event volume, whether it overlaps with peak ingestion, and whether your ClickHouse version and free disk can absorb deletes and background merges. Test the job on a copy of production-scale data before you rely on it.
How DeployOpen scopes and delivers Langfuse retention work
DeployOpen plans and implements Langfuse data retention in infrastructure you control, starting from a written scope that sets each project's window, archiving rules and verification steps. Engagements are fixed-scope, so the retention design, the changes and the handover are agreed before work begins.
How we scope
- We inventory your self-hosted Langfuse projects and record which currently keep data indefinitely and which hold data subject to other rules.
- We agree one retention window in days per project, using the three-day minimum as the floor, and document the reason for each value.
- We confirm your Enterprise license key covers data retention policies before any configuration begins, since the feature requires it when self-hosted.
How we build
- We apply the agreed window to every project through the UI or the Organization Management API, because there is no organization-level retention setting.
- We set LANGFUSE_INIT_PROJECT_RETENTION for the startup project so new environments do not begin with unlimited retention.
- We test that the nightly cleanup removes traces, observations, scores and media past the window, and that audit logs and dataset items remain.
How we hand over
- We document each project's retention value, the owner who approves changes and the review cadence for the retention register.
- We write the archiving steps to run before expiry, and confirm with you where archived data is stored and who may restore it.
- We walk your operations team through checking the cleanup job and handling deletion requests that fall outside the normal window.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, which can cover retention reviews after new projects are created.
- We can re-verify retention settings after Langfuse upgrades, since major versions change the infrastructure and data model underneath them.
- Quotes follow from the written scope, so ask for the project count, archiving work and verification effort to be itemized separately.
