media expiration.md

Data Retention & Storage

Every request to fal produces data that is stored on the platform: the JSON inputs and outputs of your request (viewable in Dashboard > Recent History), and the actual media files generated by the model (images, videos, audio) hosted on the fal CDN. This page explains how long each type of data is retained and how to control that retention.

Understanding retention matters for compliance, cost, and privacy. Generated media files are stored on the CDN and served as public URLs. Request payloads (the JSON data) are stored separately and power the request history in your dashboard. Each has its own default retention and its own header for overriding it. If you are using persistent storage (/data volume), those files are retained indefinitely and managed manually.

Generated Media (CDN Files)

When your app generates output files, they are uploaded to the fal CDN and returned as URLs (e.g., https://v3b.fal.media/files/...). Files you upload as inputs via fal_client.upload_file are also stored on the CDN. Both input uploads and output media are subject to the same retention controls.

Per-Request Expiration

Control how long generated media is stored using the X-Fal-Object-Lifecycle-Preference header:

```python Python theme={null} import fal_client import json

result = fal_client.subscribe( "fal-ai/flux/schnell", arguments={"prompt": "a sunset"}, headers={ "X-Fal-Object-Lifecycle-Preference": json.dumps({ "expiration_duration_seconds": 3600 }) } )


```javascript JavaScript theme={null}
import { fal } from "@fal-ai/client";

const result = await fal.subscribe("fal-ai/flux/schnell", {
  input: { prompt: "a sunset" },
  headers: {
    "X-Fal-Object-Lifecycle-Preference": JSON.stringify({
      expiration_duration_seconds: 3600
    })
  }
});

  curl -X POST "https://queue.fal.run/fal-ai/flux/schnell" \
    -H "Authorization: Key $FAL_KEY" \
    -H "Content-Type: application/json" \
    -H 'X-Fal-Object-Lifecycle-Preference: {"expiration_duration_seconds": 3600}' \
    -d '{"prompt": "a sunset"}'

Set expiration_duration_seconds to the number of seconds, or null for no expiration.

Expired files are permanently deleted and cannot be recovered. Download files before they expire if you need them later. The same `X-Fal-Object-Lifecycle-Preference` header also accepts an `initial_acl` field that controls **who** can access the generated files, in addition to how long they live. See [File Access Controls](/docs/documentation/model-apis/file-access-controls) for the full ACL shape and examples that combine retention with access rules.

Request Payloads

Request inputs and outputs (the JSON data) are stored in the platform for 30 days by default. This powers the request history in your dashboard.

Preventing Payload Storage

To prevent fal from storing request payloads entirely, add the X-Fal-Store-IO: 0 header:

```python Python theme={null} result = fal_client.subscribe( "fal-ai/flux/schnell", arguments={"prompt": "a sunset"}, headers={"X-Fal-Store-IO": "0"} ) ```

  const result = await fal.subscribe("fal-ai/flux/schnell", {
    input: { prompt: "a sunset" },
    headers: { "X-Fal-Store-IO": "0" }
  });

  curl -X POST "https://queue.fal.run/fal-ai/flux/schnell" \
    -H "Authorization: Key $FAL_KEY" \
    -H "X-Fal-Store-IO: 0" \
    -H "Content-Type: application/json" \
    -d '{"prompt": "a sunset"}'

This prevents storage of the JSON payloads only. CDN files generated during processing are still accessible (subject to the media expiration setting above).

Deleting Payloads

You can delete a request's payloads and the CDN files in its output via the Platform API:

Delete IO payloads and CDN output files for a specific request CDN files found in the **input** of a request are not deleted, as they may be used by other requests.

Summary

Data Type	Default Retention	Control
Generated media (CDN files)	Configurable	`X-Fal-Object-Lifecycle-Preference` header (also controls File ACLs)
Request payloads (JSON)	30 days	`X-Fal-Store-IO: 0` header to opt out, or delete via API
Persistent storage (`/data`)	Forever	Manual deletion via Dashboard or CLI