Platform Headers

When you call a model or your own deployed app on fal, you can pass platform-level HTTP headers that control how the request is handled. These headers are separate from the model’s input arguments (like prompt or image_size) and from SDK method parameters (like start_timeout or client_timeout). They apply at the infrastructure level — controlling retries, payload storage, media expiration, and routing. Some of these headers have dedicated SDK parameters that set them automatically. For example, passing start_timeout=30 in the SDK sets X-Fal-Request-Start-Timeout: 30 under the hood. Others, like X-Fal-Store-IO, can only be set via the headers dict. This page documents all platform headers in one place. For headers that have SDK parameters, the corresponding method pages are linked.

X-Fal-Request-Start-Timeout (`start_timeout`)

Server-side time-to-start deadline in seconds. The clock starts when the request is submitted and covers queue wait, runner acquisition, and failed retry attempts. Once a runner successfully begins processing, the timeout stops and inference can run as long as it needs. If the deadline is reached before any runner starts processing, fal returns 504 with X-Fal-Request-Timeout-Type: user. To limit total client-side wait time (including processing), use client_timeout on subscribe() instead.


Header	`X-Fal-Request-Start-Timeout`
Default	No timeout
Minimum	> 0.1 seconds
SDK parameter	`start_timeout` on `submit()`, `subscribe()`, and `run()`

X-Fal-Runner-Hint (`hint`)

Routing hint that tells fal to try to route the request to a specific runner. Useful for session affinity — for example, keeping requests pinned to a runner that already has a LoRA adapter or conversation state loaded in memory. If the hinted runner is unavailable, fal routes to any available runner.


Header	`X-Fal-Runner-Hint`
Default	Automatic routing
SDK parameter	`hint` on `submit()`, `subscribe()`, and `run()`

X-Fal-Queue-Priority (`priority`)

Queue priority for the request. Priority applies to the per-user per-endpoint queue. Therefore setting priority="low" on a shared model API (like fal-ai/flux/dev) deprioritizes your request relative to your other requests. Requests between users are fairly prioritized.


Header	`X-Fal-Queue-Priority`
Default	`"normal"`
Values	`"normal"`, `"low"`
SDK parameter	`priority` on `submit()` and `subscribe()`

X-Fal-Object-Lifecycle-Preference

Control how long generated files are stored on fal’s CDN and who can access them.


Header	`X-Fal-Object-Lifecycle-Preference`
Default	Your account setting (forever and publicly readable if not configured)
Format	JSON: `{"expiration_duration_seconds": <seconds>, "initial_acl": {"default": "allow"\|"forbid"\|"hide", "rules": [...]}}`
Fields	`expiration_duration_seconds` — see Data Retention. `initial_acl` — see File Access Controls. Either field is optional.

import json

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

const result = await fal.subscribe("fal-ai/nano-banana-2", {
  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/nano-banana-2" \
  -H "Authorization: Key $FAL_KEY" \
  -H 'X-Fal-Object-Lifecycle-Preference: {"expiration_duration_seconds": 3600}' \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Data Retention & Storage

Full guide to media expiration, payload retention, and the delete API

File Access Controls

Restrict who can access files on the fal CDN with per-user access rules

X-Fal-Store-IO

Prevent fal from retaining request payloads (JSON inputs and outputs) in request history. Payloads are stored for 90 days by default and power the request history in your dashboard. Your account team can configure a different account default. An explicit per-request header takes precedence.


Header	`X-Fal-Store-IO`
Default	`"1"` (stored for 90 days, unless an account default is configured)
Values	`"0"` to disable storage

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"X-Fal-Store-IO": "0"}
)

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

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

This controls request-history payload storage only. CDN files have separate retention controls. The model deployment owner controls application logging. See Zero Data Retention (ZDR) for retention controls and ZDR coverage. If you deploy your own apps, see Serverless Data Retention & Storage.

X-Fal-No-Retry

Disable automatic retries for this request. By default, queue-based requests are retried for up to 10 total attempts on server errors (503, 504, connection errors).


Header	`X-Fal-No-Retry`
Default	Retries enabled
Values	`"1"`, `"true"`, `"yes"` to disable

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"X-Fal-No-Retry": "1"}
)

const result = await fal.subscribe("fal-ai/nano-banana-2", {
  input: { prompt: "a sunset" },
  headers: { "X-Fal-No-Retry": "1" }
});

curl -X POST "https://queue.fal.run/fal-ai/nano-banana-2" \
  -H "Authorization: Key $FAL_KEY" \
  -H "X-Fal-No-Retry: 1" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Reliability & Retries

Learn more about automatic retries, fallbacks, and error handling

X-Fal-Retry-Config

Set a separate retry limit for each retry condition, instead of the all-or-nothing X-Fal-No-Retry switch. The value is a JSON object that maps a retry condition (server_error, timeout, or connection_error) to an object with a retries count. retries is the number of additional attempts after the first, so retries: 3 allows up to 4 total attempts for that condition. This header only works on your own apps — it is ignored on shared or public model APIs.


Header	`X-Fal-Retry-Config`
Default	Platform default retries per condition
Values	JSON object, e.g. `{"timeout": {"retries": 0}, "server_error": {"retries": 3}}`

import json

result = fal_client.subscribe(
    "your-username/your-app-name",
    arguments={"prompt": "a sunset"},
    headers={
        "X-Fal-Retry-Config": json.dumps(
            {"timeout": {"retries": 0}, "server_error": {"retries": 3}}
        )
    }
)

const result = await fal.subscribe("your-username/your-app-name", {
  input: { prompt: "a sunset" },
  headers: {
    "X-Fal-Retry-Config": JSON.stringify({
      timeout: { retries: 0 },
      server_error: { retries: 3 },
    }),
  }
});

curl -X POST "https://queue.fal.run/your-username/your-app-name" \
  -H "Authorization: Key $FAL_KEY" \
  -H 'X-Fal-Retry-Config: {"timeout": {"retries": 0}, "server_error": {"retries": 3}}' \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Reliability & Retries

Per-condition budgets, the overall attempt ceiling, and precedence rules

x-app-fal-disable-fallback

Disable automatic model fallbacks for this request. By default, fal may reroute requests to equivalent alternative endpoints if the primary is unavailable.


Header	`x-app-fal-disable-fallback`
Default	Fallbacks enabled

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"x-app-fal-disable-fallback": "true"}
)

const result = await fal.subscribe("fal-ai/nano-banana-2", {
  input: { prompt: "a sunset" },
  headers: { "x-app-fal-disable-fallback": "true" }
});

curl -X POST "https://queue.fal.run/fal-ai/nano-banana-2" \
  -H "Authorization: Key $FAL_KEY" \
  -H "x-app-fal-disable-fallback: true" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Reliability & Retries

Learn more about model fallbacks

X-Fal-Tags

Attach your own key=value tags to the request. Use tags to attribute spend to a team, an environment, or a feature. fal reports usage and estimated cost against the tags it activates for your account.

Availability: Tag reporting must be enabled for your account. Contact your account team or support@fal.ai to request access, and name the tag keys and values to activate.

Tag reporting covers per-request-billed calls to Model APIs. fal does not capture tags on a WebSocket connection, and it does not attribute per-request cost for your own deployed apps yet.


Header	`X-Fal-Tags`
Default	No tags
Format	`key=value` tags, separated by commas, e.g. `team=design,env=prod`
Limits	10 tags per request. Key 64 characters, value 256 characters, 1 KB in total.

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"X-Fal-Tags": "team=design,env=prod"}
)

const result = await fal.subscribe("fal-ai/nano-banana-2", {
  input: { prompt: "a sunset" },
  headers: { "X-Fal-Tags": "team=design,env=prod" }
});

curl -X POST "https://queue.fal.run/fal-ai/nano-banana-2" \
  -H "Authorization: Key $FAL_KEY" \
  -H "X-Fal-Tags: team=design,env=prod" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Request Tags

The full rules, the activation step, and where tagged usage appears

X-Fal-Workflow-Envelope

Add the endpoint and the request ID of each step to the result of a workflow. The result becomes {"output": ..., "nodes": ...}. The webhook payload contains the same result. fal reads this header only for workflows.


Header	`X-Fal-Workflow-Envelope`
Default	`"false"` (the result contains only the output)
Values	`"true"`

handler = fal_client.submit(
    "workflows/<user>/<workflow>",
    arguments={"prompt": "a sunset"},
    headers={"X-Fal-Workflow-Envelope": "true"}
)

const { request_id } = await fal.queue.submit("workflows/<user>/<workflow>", {
  input: { prompt: "a sunset" },
  headers: { "X-Fal-Workflow-Envelope": "true" },
});

curl -X POST "https://queue.fal.run/workflows/<user>/<workflow>" \
  -H "Authorization: Key $FAL_KEY" \
  -H "X-Fal-Workflow-Envelope: true" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Step request IDs

The result format, the error body, and how to get the cost of each step

fal_max_queue_length

Reject the request with 429 if the endpoint’s queue already has more than this many requests waiting (across all callers). Useful for latency-sensitive applications that prefer to fail fast rather than wait in a long queue.


Query param	`fal_max_queue_length`
Default	No limit
Type	Integer

This parameter is passed as a query parameter on the URL, not as a header. The SDKs do not currently expose it as a named parameter; use the raw URL approach or pass it via headers.

cURL

curl -X POST "https://queue.fal.run/fal-ai/nano-banana-2?fal_max_queue_length=10" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

Response Headers

These headers are returned by fal in the response. They are informational; you don’t set them.

The total size of all response headers is limited to 16 KB. This includes both platform headers (listed below) and any custom headers set by the app. If the combined headers exceed 16 KB, the response will fail. This is most relevant when apps set large custom headers — for example, verbose routing hints via provide_hints().

Header	Description
`x-fal-request-id`	Unique identifier for the request. Use this when contacting support or correlating logs.
`X-Fal-Billable-Units`	Billing units charged for this request. See Pricing for how units map to cost.
`X-Fal-Served-From`	Internal identifier of the runner that served the request.
`X-Fal-Request-Timeout-Type`	Set to `user` when your `start_timeout` deadline triggered the 504. See Timeouts and Retries.
`X-Fal-Error-Type`	Error category on failure responses (e.g., `request_timeout`, `startup_timeout`, `runner_disconnected`). See Request Error Types.
`x-fal-runner-hints`	Routing hints returned by the runner for sticky session routing. See Optimize Routing Behavior.
`X-Fal-Tags-Dropped`	Set to `1` when fal dropped some `X-Fal-Tags` content. Absent when fal kept every tag.

Common Model Arguments

Common input parameters like seed, image_size, and safety checker that appear across many models

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

Platform Headers

X-Fal-Request-Start-Timeout (`start_timeout`)

X-Fal-Runner-Hint (`hint`)

X-Fal-Queue-Priority (`priority`)

X-Fal-Object-Lifecycle-Preference

Data Retention & Storage

File Access Controls

X-Fal-Store-IO

X-Fal-No-Retry

Reliability & Retries

X-Fal-Retry-Config

Reliability & Retries

x-app-fal-disable-fallback

Reliability & Retries

X-Fal-Tags

Request Tags

X-Fal-Workflow-Envelope

Step request IDs

fal_max_queue_length

Response Headers

Common Model Arguments

​X-Fal-Request-Start-Timeout (start_timeout)

​X-Fal-Runner-Hint (hint)

​X-Fal-Queue-Priority (priority)

​X-Fal-Object-Lifecycle-Preference

Data Retention & Storage

File Access Controls

​X-Fal-Store-IO

​X-Fal-No-Retry

Reliability & Retries

​X-Fal-Retry-Config

Reliability & Retries

​x-app-fal-disable-fallback

Reliability & Retries

​X-Fal-Tags

Request Tags

​X-Fal-Workflow-Envelope

Step request IDs

​fal_max_queue_length

​Response Headers

Common Model Arguments

X-Fal-Request-Start-Timeout (`start_timeout`)

X-Fal-Runner-Hint (`hint`)

X-Fal-Queue-Priority (`priority`)

X-Fal-Object-Lifecycle-Preference

X-Fal-Store-IO

X-Fal-No-Retry

X-Fal-Retry-Config

x-app-fal-disable-fallback

X-Fal-Tags

X-Fal-Workflow-Envelope

fal_max_queue_length

Response Headers