Request Headers

For each request to your fal App, fal adds headers such as the request ID and caller identity. The system also forwards custom headers from the caller. You can read these inside your endpoint handler via self.current_request.headers.get(). Request headers are per-request context, complementing environment variables which are per-runner context. Use headers when you need to identify the specific request or caller (for logging, tracing, or per-user logic), and environment variables for runner-wide information like FAL_APP_NAME or FAL_KEY.

import fal
from pydantic import BaseModel

class Input(BaseModel):
    prompt: str

class MyApp(fal.App):
    machine_type = "GPU-A100"

    @fal.endpoint("/")
    def generate(self, input: Input) -> dict:
        request_id = self.current_request.headers.get("x-fal-request-id")
        caller_id = self.current_request.headers.get("x-fal-caller-user-id")

        print(f"Request {request_id} from {caller_id}")
        return {"result": "..."}

Available Headers

Header	Description
`x-fal-request-id`	Unique identifier for this request. Use for log correlation and debugging.
`x-fal-caller-user-id`	The caller’s user ID (hashed for third-party apps). Useful for per-user logic.
`x-fal-cdn-token`	Token issued by fal for CDN downloads and uploads on behalf of the caller. Use `Authorization: Bearer <token>` for downloads. See Serverless file handling.
`x-fal-endpoint`	The full endpoint path being called (e.g., `your-user/your-app/`).

Custom headers passed by the caller are also forwarded to your app. Most headers that start with x-fal- are reserved for the gateway, and a caller cannot set them. The documented platform headers are the exception. A caller can set those, including X-Fal-Tags, but the gateway handles them and does not forward them to your app.

Correlating with External Tools

Sentry

Attach the request ID to Sentry events so you can find the exact fal request that caused an error:

import fal
from pydantic import BaseModel

class Input(BaseModel):
    prompt: str

class MyApp(fal.App):
    machine_type = "GPU-A100"
    requirements = ["sentry-sdk"]

    def setup(self):
        import sentry_sdk
        sentry_sdk.init(dsn="https://your-sentry-dsn")
        self.model = load_model()

    @fal.endpoint("/")
    def generate(self, input: Input) -> dict:
        import sentry_sdk
        sentry_sdk.set_tag("fal_request_id", self.current_request.headers.get("x-fal-request-id"))
        return {"image": self.model(input.prompt)}

Structured Logging

Include the request ID in your log output for correlation with fal’s built-in logs:

import fal
import logging
from pydantic import BaseModel

logger = logging.getLogger(__name__)

class Input(BaseModel):
    prompt: str

class MyApp(fal.App):
    machine_type = "GPU-A100"

    @fal.endpoint("/")
    def generate(self, input: Input) -> dict:
        rid = self.current_request.headers.get("x-fal-request-id")
        logger.info("Processing request", extra={"request_id": rid})

        result = self.model(input.prompt)

        logger.info("Request complete", extra={"request_id": rid})
        return {"image": result}

Custom Headers

Callers can pass custom headers that are forwarded to your app:

# Caller passes a custom header
result = fal_client.subscribe("your-user/your-app", arguments={
    "prompt": "a sunset"
}, headers={
    "X-My-Trace-Id": "abc-123",
    "X-My-User-Tier": "premium"
})

# Your app reads it
class Input(BaseModel):
    prompt: str

@fal.endpoint("/")
def generate(self, input: Input) -> dict:
    trace_id = self.current_request.headers.get("x-my-trace-id")
    user_tier = self.current_request.headers.get("x-my-user-tier")
    ...

Header names are case-insensitive. X-My-Header and x-my-header both work.

Response Header Size Limit

The total size of all response headers returned by your app is limited to 16 KB. This includes platform headers injected by fal (like x-fal-request-id and X-Fal-Billable-Units) and any custom headers your app sets, such as billing units or routing hints from provide_hints(). If the combined headers exceed 16 KB, the response will fail. Keep custom header values short. If you use provide_hints(), avoid returning large lists of model names or long strings — each hint value contributes to the total header size.

The system processes platform headers like X-Fal-Request-Start-Timeout, X-Fal-No-Retry, X-Fal-Retry-Config, X-Fal-Store-IO, and X-Fal-Tags before requests reach your runner. These controls are not available in self.current_request.headers. Your app receives the identity and CDN headers listed above, along with custom caller headers.

Environment Variables

Per-runner context: FAL_KEY, FAL_APP_NAME, FAL_RUNNER_STATE, and more

Setting Up

Model APIs

Serverless

Compute

Organizations

fal Agent

fal Assets

Request Headers

Available Headers

Correlating with External Tools

Sentry

Structured Logging

Custom Headers

Response Header Size Limit

Environment Variables

​Available Headers

​Correlating with External Tools

​Sentry

​Structured Logging

​Custom Headers

​Response Header Size Limit

Environment Variables

Available Headers

Correlating with External Tools

Sentry

Structured Logging

Custom Headers

Response Header Size Limit