Modal logo
Python SDK Reference App Client CloudBucketMount Cls Cluster Cron Dict Environment Error FilePatternMatcher Function FunctionCall Image Period Probe Proxy Queue Retries Sandbox SandboxSnapshot Secret Server Tunnel Volume Workspace asgi_app batched billing clustered concurrent config container_process current_function_call_id current_input_id enable_output enter exception exit fastapi_endpoint forward interact io_streams is_local method parameter sessioned types web_server wsgi_app

types

Public data types returned by Modal APIs.

AppInfo

Information about a modal App, including its lifecycle and member functions and servers.

Attributes

app_id str
description str
lifecycle AppLifecycle
functions dict[str, str]
servers dict[str, str]

AppLifecycle

Timestamps and attributions for events in an App's lifecycle.

Timestamps or attributions may be None when they do not apply to this App (e.g., App is not deployed, App was not explicitly stopped).

Attributes

state AppState
version int | None
created_at datetime
created_by str
deployed_at datetime | None
deployed_by str | None
stopped_at datetime | None
stopped_by str | None

AppState

class AppState(str, enum.Enum)

An enumeration.

The possible values are:

  • EPHEMERAL
  • DETACHED
  • DEPLOYED
  • STOPPING
  • STOPPED
  • INITIALIZING
  • DISABLED

BillingReportItem

Costs generated by a specific object during a specific time interval.

Attributes

object_id str
description str
environment_name str
interval_start datetime
cost Decimal
cost_by_resource dict[str, Decimal]
tags dict[str, str]

CloudBucketMountInfo

Attributes

bucket_name str
bucket_type Literal["s3", "r2", "gcp"]
read_only bool
key_prefix str | None

DictInfo

Information about a Dict object.

Attributes

name str | None
created_at datetime
created_by str | None

EnvironmentBillingSummary

Attributes

start datetime
end datetime
metered_cost Decimal
metered_cost_breakdown dict[str, Decimal]

FileEntry

A file or directory entry listed from a Modal volume.

Attributes

path str
type FileEntryType
mtime int
size int

FileEntryType

class FileEntryType(enum.IntEnum)

Type of a file entry listed from a Modal volume.

The possible values are:

  • UNSPECIFIED
  • FILE
  • DIRECTORY
  • SYMLINK
  • FIFO
  • SOCKET

FileInfo

Metadata for a file or directory entry in a Sandbox.

Attributes

name str
path str
type FileType
size int
mode int
permissions str
owner str
group str
modified_time float
symlink_target str | None

is_file

is_file(self)

Return True if this entry is a regular file.

is_dir

is_dir(self)

Return True if this entry is a directory.

is_symlink(self)

Return True if this entry is a symbolic link.

FileType

class FileType(enum.Enum)

Type of a filesystem entry.

The possible values are:

  • FILE
  • DIRECTORY
  • SYMLINK

FileWatchEvent

A filesystem change event reported by Sandbox.filesystem.watch().

paths contains the absolute path(s) affected by the event. For most event types it holds a single entry. Rename operations are reported as Modify events: when both the source and destination fall within the watched scope, paths holds [source, destination]; when only one side of the rename is visible, paths holds that single path.

Attributes

paths list[str]
type FileWatchEventType

FileWatchEventType

class FileWatchEventType(enum.Enum)

Type of a filesystem watch event reported by Sandbox.filesystem.watch().

The possible values are:

  • Unknown
  • Access
  • Create
  • Modify
  • Remove

FunctionAutoscalerSettings

Attributes

min_containers int | None
max_containers int | None
scaledown_window int | None
buffer_containers int | None

FunctionCurrentStats

Simple data structure storing stats for a running function.

Attributes

backlog int
num_total_runners int
num_running_inputs int
input_headroom int

FunctionInfo

A simple data structure containing static info about a Function handle.

Attributes

cpu float | tuple[float, float] | None
memory_mib int | tuple[int, int] | None
gpus list[tuple[str, int]]
ephemeral_disk_mib int | None
image_info ImageInfo
image_name str | None
image_id str | None
startup_timeout int | None
timeout int
max_retries int | None
nonpreemptible bool
regions list[str] | None
routing_region str | None
cloud str | None
cluster_info ClusterInfo | None
size int
rdma bool
fabric_size int | None
batching_info BatchingInfo | None
max_batch_size int
wait_ms int
concurrency_info ConcurrencyInfo | None
max_inputs int | None
target_inputs int | None
schedule str | None
restrict_modal_access bool
block_network bool
single_use_containers bool
volumes dict[str, VolumeMountInfo]
cloud_bucket_mounts dict[str, CloudBucketMountInfo]
secrets list[str]
web_info WebInfo | None
web_url str
method str | None
unauthenticated bool
method_names list[str] | None
method_details dict[str, WebInfo] | None
web_url str
method str | None
unauthenticated bool

FunctionStats

Historical Function statistics for a time range.

Attributes

since datetime
until datetime
input_success_count int
input_failure_count int
input_timeout_count int
input_running_at_end_count int
input_percentile_stats dict[str, StatsPercentileDistribution]
container_started_count int
container_error_count int
container_creating_at_end_count int
container_percentile_stats dict[str, StatsPercentileDistribution]
container_total_count int
variant_count int
all_variants bool

InputInfo

Simple data structure storing information about a function input.

Attributes

input_id str
function_call_id str
task_id str
status InputStatus
function_name str
module_name str
children list["InputInfo"]

InputStatus

class InputStatus(enum.IntEnum)

Enum representing status of a function input.

The possible values are:

  • PENDING
  • SUCCESS
  • FAILURE
  • INIT_FAILURE
  • TERMINATED
  • TIMEOUT

LogEntry

A log entry queried through a Modal object or App.

The object_id field identifies the object or App whose log manager produced the entry. The context_ids field contains progressively narrower IDs corresponding to the context in which the log entry was emitted. For example, for a function log entry, this will contain the function call ID, the input ID, and the container ID.

Attributes

message str
timestamp datetime
source LogSource
object_id str
context_ids list[str]

ProxyTokenInfo

Metadata about a proxy token, not including the token secret.

Attributes

token_id str
created_at datetime
scoped bool
name str
(Default is '' )
created_by str
(Default is '' )

QueueInfo

Information about a Queue object.

Attributes

name str | None
created_at datetime
created_by str | None

SandboxConnectCredentials

Simple data structure storing credentials for making HTTP connections to a sandbox.

Attributes

url str
token str

SecretInfo

Information about a Secret object.

Attributes

name str | None
environment_name str
created_at datetime
created_by str | None

ServerAutoscalerSettings

Attributes

target_concurrency int | float | None
min_containers int | None
max_containers int | None
buffer_containers int | None
scaleup_window int | None
scaledown_window int | None

ServerContainerInfo

Information about a container serving requests for a Server.

Attributes

container_id str
host str
port int

ServerInfo

A simple data structure containing static info about a Server handle.

Attributes

server_url str
port int
unauthenticated bool
h2_enabled bool
routing_region str | None
sessioned bool
startup_timeout int
exit_grace_period int
image_info ImageInfo
image_name str | None
image_id str | None
cpu float | tuple[float, float] | None
memory_mib int | tuple[int, int] | None
gpus list[tuple[str, int]]
ephemeral_disk_mib int | None
nonpreemptible bool
compute_regions list[str] | None
cloud str | None
cluster_info ClusterInfo | None
size int
rdma bool
fabric_size int | None
volumes dict[str, VolumeMountInfo]
cloud_bucket_mounts dict[str, CloudBucketMountInfo]
secrets list[str]

ServerSessionCredentials

Credentials for a sticky session on a Server.

Requests carrying token are routed to the same container.

Attributes

session_id str
token str

ServerStats

Historical Server statistics for a time range.

Attributes

since datetime
until datetime
request_count int
request_count_by_status_code dict[int, int]
request_rate_per_second float
request_percentile_stats dict[str, StatsPercentileDistribution]
container_started_count int
container_error_count int
container_creating_at_end_count int
container_total_count int
container_percentile_stats dict[str, StatsPercentileDistribution]
inference InferenceStats | None

Inference-engine statistics for a Server.

engine str
status str
percentile_stats dict[str, StatsPercentileDistribution]
scalar_stats dict[str, float]

StatsPercentile

A percentile measurement for a metric or strat.

Attributes

percentile float
value float

StatsPercentileDistribution

Attributes

unit str
percentiles list[StatsPercentile]

TokenData

A token ID / secret pair.

Attributes

token_id str
token_secret str

VolumeCreateOptions

Options used when creating a Volume.

Attributes

experimental_options NotRequired[dict[str, Any]]

VolumeInfo

Information about a Volume object.

Attributes

name str | None
created_at datetime
created_by str | None

VolumeMountInfo

Attributes

name str | None
volume_id str | None
read_only bool
sub_path str | None

WorkspaceBillingSummary

Attributes

start datetime
end datetime
metered_cost Decimal
metered_cost_breakdown dict[str, Decimal]
adjustments dict[str, Decimal]
billed_cost Decimal

WorkspaceMemberInfo

Metadata about a Workspace member.

Attributes

name str
email str
user_id str
role str
joined_at datetime
last_active_at Optional[datetime]

WorkspaceSettings

Current settings for the workspace.

Attributes

default_environment str
image_builder_version str