File Retention & Data Lifecycle
Overview
File retention lets you define how long uploaded documents are stored inside a project. When a document exceeds the configured age, Ocriva automatically removes the file from cloud storage and marks the associated records as expired. This helps manage storage costs and keeps your projects free of stale data.
Retention is configured at the project level via the fileRetentionDays setting. Projects without this setting never auto-expire files.
How It Works
Ocriva runs a background job every minute that scans all projects with a fileRetentionDays value greater than zero. For each such project, it looks for uploads older than the configured number of days that have not already been expired.
Expiry process for each matched upload:
- The file's storage quota contribution is subtracted from the organization's usage counter
- The physical file is deleted from cloud storage (Supabase Storage or GCS)
- The upload record's status is set to
retention_expired - All associated processing history records are also set to
retention_expired
IMPORTANT
File expiry is permanent and irreversible. Once a file is deleted by the retention job, neither the file nor its raw content can be recovered. Extraction results in your processing history remain accessible (in expired state), but the original document is gone.
Configuring Retention for a Project
The retention period is set on the project's settings.fileRetentionDays field. A value of 0 or the absence of this field means files are retained indefinitely.
Via the API (create or update project):
{
"settings": {
"fileRetentionDays": 90
}
}Setting fileRetentionDays to 90 means any upload older than 90 days will be expired on the next retention job run.
NOTE
Setting fileRetentionDays on an existing project takes effect at the next scheduled run. Files already older than the configured threshold will be expired within one minute of the setting being saved.
Retention Status Values
After a file is processed by the retention job, both the upload record and its processing history entries are updated to reflect the expiry:
| Status | Meaning |
|---|---|
retention_expired | The file has been deleted from storage by the retention job. The record still exists for audit purposes but the original file is no longer accessible. |
Any other upload status indicates the file is still present in storage and has not been expired.
Storage Usage and Billing
When a file expires, its size is deducted from your organization's storage usage counter. This means:
- Storage usage drops automatically as files age out
- You do not need to manually delete files to free up quota on projects with retention enabled
- If the storage deduction step fails (e.g., a transient error), the job logs a warning and continues processing remaining files — the file is still marked expired in the database
NOTE
Storage quota is tracked in gigabytes. Very small files (under 1 KB) may round to zero in the usage counter but are still deleted from storage.
Project Settings Reference
The following project settings are relevant to file management. All are optional and default to the values shown.
| Setting | Type | Default | Description |
|---|---|---|---|
fileRetentionDays | number | (unset) | Number of days before uploaded files are auto-expired. Unset or 0 means no automatic expiry. |
maxDocumentsPerMonth | number | 100 | Monthly upload limit for the project. |
allowMembersToUploadDocuments | boolean | true | Whether project members (non-owners) can upload new documents. |
allowMembersToViewAllDocuments | boolean | false | Whether members can see documents uploaded by other members. |
allowMembersToCreateTemplates | boolean | true | Whether members can create new extraction templates. |
maxTemplatesPerProject | number | 10 | Maximum number of templates allowed in the project. |
Recommendations
- Set a retention period on projects used for testing or experimentation. A value of
7to30days keeps test uploads from accumulating indefinitely. - Use longer retention (90–365 days) for production projects where you may need to re-process documents or refer back to originals.
- Leave
fileRetentionDaysunset for archival projects where permanent document storage is required. - Monitor storage usage in the Billing page to understand the impact before enabling short retention periods on high-volume projects.
- Export results before retention expires. If your workflow depends on original files, download or forward them to long-term storage before the retention window closes.