Skip to main content
The SyncServerlessClient is the synchronous Python client for interacting with fal Serverless. Its namespaces and methods mirror the CLI so you can automate the same workflows from Python.

​
Import and Initialize

from fal.api import SyncServerlessClient

client = SyncServerlessClient(
    host=None,     # Optional. Override API host
    api_key=None,  # Optional. If omitted, read from env/profile
    profile=None,  # Optional. Named profile to use
    team=None,     # Optional. Team context for runner ops
)

​
Overview of Namespaces

  • client.apps.* — corresponds to fal apps ...
  • client.runners.* — corresponds to fal runners ...
  • client.deploy(...) — corresponds to fal deploy ...

​
Apps Namespace

Manage your applications: list them, view runners for a specific app, and adjust scaling.

​
List Applications (fal apps list)

apps = client.apps.list()

# Optional app name filter
filtered = client.apps.list(filter="stable")

​
List App Runners (fal apps runners my-app)

app_runners = client.apps.runners("my-app")

# Optional filters
recent = client.apps.runners("my-app", since=datetime.now() - timedelta(hours=1)) # last hour
running_only = client.apps.runners("my-app", state=["running"])                   # by state

​
Scale Application (fal apps scale)

Maps to CLI flags in fal apps scale. Any omitted option keeps the current value. 
client.apps.scale(
    "my-app",
    keep_alive=300,            # seconds
    max_multiplexing=1,
    max_concurrency=10,
    min_concurrency=1,
    request_timeout=600,       # seconds
    startup_timeout=900,       # seconds
    machine_types=["GPU-H100", "GPU-H200"],
    regions=["us-east-1", "us-west-2"],
    concurrency_buffer=1,
    concurrency_buffer_perc=10,
)

​
Runners Namespace

List and manage runners.

​
List Runners (fal runners list)

all_runners = client.runners.list()

# Recent runners only
last_10_min = client.runners.list(since=datetime.now() - timedelta(minutes=10))

​
Deploy (fal deploy)

Programmatic equivalent of fal deploy. If app_ref is omitted, discovery behavior matches the CLI (e.g., pyproject.toml). 
# Auto-discover
client.deploy()

# Deploy from a file path
client.deploy("path/to/myfile.py")

# Deploy a specific class in a file
client.deploy("path/to/myfile.py::MyApp")

# Deploy by existing app name
client.deploy("my-app")

# With options mirroring CLI flags
client.deploy(
    app_ref="path/to/myfile.py::MyApp",
    app_name="myapp",
    auth="public",                # "private" | "public"
    strategy="rolling"            # "recreate" | "rolling"
    reset_scale=True,             # use previous scaling if False
)

​
Reference

For the complete Python API surface (types, dataclasses, and method signatures), see the auto-generated API reference.