fal.api

from fal.api import (
    SyncServerlessClient,
    AppsNamespace,
    RunnersNamespace,
    KeysNamespace,
    SecretsNamespace,
)

Classes

SyncServerlessClient

class fal.api.SyncServerlessClient

Synchronous Python client for fal Serverless. Manage apps, runners, and deployments programmatically. The namespaces and methods mirror the CLI so you can automate the same workflows from Python. Example:

from fal.api import SyncServerlessClient

client = SyncServerlessClient()

# List apps
apps = client.apps.list()

# Scale an app
client.apps.scale("my-app", max_concurrency=10)

# Deploy
client.deploy("path/to/myfile.py::MyApp")

Namespaces:

client.apps.* - corresponds to fal apps ...
client.runners.* - corresponds to fal runners ...
client.keys.* - corresponds to fal keys ...
client.secrets.* - corresponds to fal secrets ...
client.deploy() - corresponds to fal deploy ...

Constructor Parameters

Name	Type	Default	Description
`host`	`Optional[str]`	`None`	Optional. Override API host.
`api_key`	`Optional[str]`	`None`	Optional. If omitted, read from env/profile.
`profile`	`Optional[str]`	`None`	Optional. Named profile to use.
`team`	`Optional[str]`	`None`	Optional. Team context for runner operations.

Class Variables

Name	Type	Default	Description
`host`	`Optional[str]`	`None`	-
`api_key`	`Optional[str]`	`None`	-
`profile`	`Optional[str]`	`None`	-
`team`	`Optional[str]`	`None`	-

Properties

Name	Type	Description
`_credentials`	`Credentials`	-
`_grpc_host`	`str`	-
`_rest_url`	`str`	-

Methods

deploy

def deploy(self, *args, **kwargs)

Deploy an application. Corresponds to fal deploy. If app_ref is omitted, discovery behavior matches the CLI (e.g., uses pyproject.toml).Example:

# Auto-discover from pyproject.toml
client.deploy()

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

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

# With options
client.deploy(
    app_ref="path/to/myfile.py::MyApp",
    app_name="myapp",
    auth="public",
    strategy="rolling",
)

Parameter	Type	Default	Description
`args`	-	-	-
`kwargs`	-	-	-

AppsNamespace

class fal.api.AppsNamespace

Namespace for app management operations. Corresponds to fal apps ... CLI commands. Accessed via client.apps. Example:

from fal.api import SyncServerlessClient

client = SyncServerlessClient()
apps = client.apps.list()
client.apps.scale("my-app", max_concurrency=10)

Constructor Parameters

Name	Type	Default	Description
`client`	`SyncServerlessClient`	-	-

Methods

gpus

def gpus(self, app_name: 'str') -> 'dict'

Get GPU usage for a single application. Corresponds to fal apps gpus \<app\>. Returns \{"gpus": \{\<type\>: \<count\>, ...\}, "total": \<int\>\}.Example:

usage = client.apps.gpus("fal-ai/flux")
print(usage["total"])  # e.g. 21
print(usage["gpus"])   # e.g. {"B200": 21}

Parameter	Type	Default	Description
`app_name`	`str`	-	-

Returns: dict

list

def list(self, *, filter: 'str | None' = None, environment_name: 'str | None' = None) -> 'List[AliasInfo]'

List all applications. Corresponds to fal apps list.Example:

apps = client.apps.list()
filtered = client.apps.list(filter="stable")

Parameter	Type	Default	Description
`filter`	`Optional[str]`	`None`	Optional app name filter string.
`environment_name`	`Optional[str]`	`None`	Optional environment name.

Returns: list[AliasInfo]

rollout

def rollout(self, app_name: 'str', *, force: 'bool' = False, environment_name: 'str | None' = None) -> 'None'

Parameter	Type	Default	Description
`app_name`	`str`	-	-
`force`	`bool`	`False`	-
`environment_name`	`Optional[str]`	`None`	-

Returns: NoneType

runners

def runners(self, app_name: 'str', *, since=None, state: 'List[str] | None' = None, environment_name: 'str | None' = None) -> 'List[RunnerInfo]'

List runners for a specific app. Corresponds to fal apps runners \<app\>.Example:

from datetime import datetime, timedelta

runners = client.apps.runners("my-app")
recent = client.apps.runners(
    "my-app", since=datetime.now() - timedelta(hours=1)
)
running = client.apps.runners("my-app", state=["running"])

Parameter	Type	Default	Description
`app_name`	`str`	-	Name of the application.
`since`	-	`None`	Only return runners started after this datetime.
`state`	`Optional[list[str]]`	`None`	Filter by runner state (e.g., [“running”]).
`environment_name`	`Optional[str]`	`None`	Optional environment name.

Returns: list[RunnerInfo]

scale

def scale(self, app_name: 'str', *, keep_alive: 'int | None' = None, max_multiplexing: 'int | None' = None, max_concurrency: 'int | None' = None, min_concurrency: 'int | None' = None, concurrency_buffer: 'int | None' = None, concurrency_buffer_perc: 'int | None' = None, scaling_delay: 'int | None' = None, request_timeout: 'int | None' = None, startup_timeout: 'int | None' = None, machine_types: 'List[str] | None' = None, regions: 'List[str] | None' = None, environment_name: 'str | None' = None) -> 'apps_api.AliasInfo'

Adjust scaling settings for an application. Corresponds to fal apps scale. Any omitted option keeps the current value.Example:

client.apps.scale(
    "my-app",
    keep_alive=300,
    max_concurrency=10,
    min_concurrency=1,
    machine_types=["GPU-H100", "GPU-H200"],
)

Parameter	Type	Default	Description
`app_name`	`str`	-	Name of the application.
`keep_alive`	`Optional[int]`	`None`	Keep-alive time in seconds.
`max_multiplexing`	`Optional[int]`	`None`	Maximum request multiplexing.
`max_concurrency`	`Optional[int]`	`None`	Maximum concurrent runners.
`min_concurrency`	`Optional[int]`	`None`	Minimum concurrent runners.
`concurrency_buffer`	`Optional[int]`	`None`	-
`concurrency_buffer_perc`	`Optional[int]`	`None`	-
`scaling_delay`	`Optional[int]`	`None`	-
`request_timeout`	`Optional[int]`	`None`	Request timeout in seconds.
`startup_timeout`	`Optional[int]`	`None`	Startup timeout in seconds.
`machine_types`	`Optional[list[str]]`	`None`	List of allowed machine types (e.g., [“GPU-H100”]).
`regions`	`Optional[list[str]]`	`None`	List of allowed regions (e.g., [“us-east”]).
`environment_name`	`Optional[str]`	`None`	-

Returns: AliasInfo

RunnersNamespace

class fal.api.RunnersNamespace

Namespace for runner management operations. Corresponds to fal runners ... CLI commands. Accessed via client.runners. Example:

from fal.api import SyncServerlessClient

client = SyncServerlessClient()
runners = client.runners.list()
client.runners.stop("runner-id")

Constructor Parameters

Name	Type	Default	Description
`client`	`SyncServerlessClient`	-	-

Methods

gpus

def gpus(self) -> 'dict'

Get team-wide GPU usage summary. Corresponds to fal runners gpus. Returns \{"gpus": \{\<type\>: \<count\>, ...\}, "total": \<int\>\}.Example:

usage = client.runners.gpus()
print(usage["total"])  # e.g. 1120
print(usage["gpus"])   # e.g. {"H100": 394, "B200": 353, ...}

Returns: dict

kill

def kill(self, runner_id: 'str') -> 'None'

Forcefully kill a runner.

Parameter	Type	Default	Description
`runner_id`	`str`	-	The ID of the runner to kill.

Returns: NoneType

list

def list(self, *, since=None) -> 'List[RunnerInfo]'

List all runners. Corresponds to fal runners list.Example:

from datetime import datetime, timedelta

all_runners = client.runners.list()
recent = client.runners.list(since=datetime.now() - timedelta(minutes=10))

Parameter	Type	Default	Description
`since`	-	`None`	Only return runners started after this datetime.

Returns: list[RunnerInfo]

stop

def stop(self, runner_id: 'str', replace_first: 'bool' = False) -> 'None'

Gracefully stop a runner.

Parameter	Type	Default	Description
`runner_id`	`str`	-	The ID of the runner to stop.
`replace_first`	`bool`	`False`	Whether to replace the runner before stopping it.

Returns: NoneType

KeysNamespace

class fal.api.KeysNamespace

Namespace for API key management. Corresponds to fal keys ... CLI commands. Accessed via client.keys. Example:

from fal.api import SyncServerlessClient

client = SyncServerlessClient()
keys = client.keys.list()
key_id, key_secret = client.keys.create(scope="admin")

Constructor Parameters

Name	Type	Default	Description
`client`	`SyncServerlessClient`	-	-

Methods

create

def create(self, *, scope: 'KeyScope', description: 'str | None' = None) -> 'tuple[str, str]'

Create a new API key.

Parameter	Type	Default	Description
`scope`	`KeyScope`	-	Key scope (e.g., “admin”).
`description`	`Optional[str]`	`None`	Optional description for the key.

Returns: tuple[str, str]

list

def list(self) -> 'List[UserKeyInfo]'

List all API keys.Returns: list[UserKeyInfo]

revoke

def revoke(self, key_id: 'str') -> 'None'

Revoke an API key.

Parameter	Type	Default	Description
`key_id`	`str`	-	The ID of the key to revoke.

Returns: NoneType

SecretsNamespace

class fal.api.SecretsNamespace

Namespace for secrets management. Corresponds to fal secrets ... CLI commands. Accessed via client.secrets. Example:

from fal.api import SyncServerlessClient

client = SyncServerlessClient()
client.secrets.set("API_KEY", "my-secret-value")
secrets = client.secrets.list()

Constructor Parameters

Name	Type	Default	Description
`client`	`SyncServerlessClient`	-	-

Methods

list

def list(self, environment_name: 'str | None' = None) -> 'List[ServerlessSecret]'

List all secrets (names only, not values).

Parameter	Type	Default	Description
`environment_name`	`Optional[str]`	`None`	-

Returns: list[ServerlessSecret]

set

def set(self, name: 'str', value: 'str', environment_name: 'str | None' = None, default_exposed: 'bool | None' = None) -> 'None'

Set a secret value.

Parameter	Type	Default	Description
`name`	`str`	-	Name of the secret.
`value`	`str`	-	Value to store.
`environment_name`	`Optional[str]`	`None`	Optional environment name.
`default_exposed`	`Optional[bool]`	`None`	Whether the secret is exposed to apps that do not explicitly list their secrets. None keeps the account-level default (and preserves the current setting on updates).

Returns: NoneType

unset

def unset(self, name: 'str', environment_name: 'str | None' = None) -> 'None'

Delete a secret.

Parameter	Type	Default	Description
`name`	`str`	-	Name of the secret to delete.
`environment_name`	`Optional[str]`	`None`	Optional environment name.

Returns: NoneType

Client Libraries

CLI Reference

Python SDK

Classes

SyncServerlessClient

deploy

AppsNamespace

gpus

list

rollout

runners

scale

RunnersNamespace

gpus

kill

list

stop

KeysNamespace

create

list

revoke

SecretsNamespace

list

set

unset

​Classes

​SyncServerlessClient

​deploy

​AppsNamespace

​gpus

​list

​rollout

​runners

​scale

​RunnersNamespace

​gpus

​kill

​list

​stop

​KeysNamespace

​create

​list

​revoke

​SecretsNamespace

​list

​set

​unset

Classes

SyncServerlessClient

deploy

AppsNamespace

gpus

list

rollout

runners

scale

RunnersNamespace

gpus

kill

list

stop

KeysNamespace

create

list

revoke

SecretsNamespace

list

set

unset