Workspace

class Workspace(modal.object.Object)

hydrate

hydrate(self, client=None)

Synchronize the local object with its identity on the Modal server.

It is rarely necessary to call this method explicitly, as most operations will lazily hydrate when needed. The main use case is when you need to access object metadata, such as its ID.

Added in v0.72.39: This method replaces the deprecated .resolve() method.

name

name(self)

members

members: WorkspaceMembersManager

Namespace with methods for managing the membership of a Workspace.

members.list

list(self)

Return the members of the Workspace.

Examples:

members = modal.Workspace.from_context().members.list()
print([m.name for m in members])

from_context

from_context(*, client=None)

Look up the Workspace associated with the current context.

This returns the Workspace that the active Modal credentials authenticate against (i.e., your active profile or the MODAL_TOKEN_ID / MODAL_TOKEN_SECRET environment variables). If called inside a Modal container, it returns the Workspace that the container is running in.

billing

billing: WorkspaceBillingManager

Namespace for Workspace billing APIs.

billing.rates

rates(self)

Return current pricing rates for the given workspace.

Returns

A single mapping containing cost values. All values are reported as decimal.Decimals.

billing.report

report(self, *, start, end=None, resolution="d", tag_names=None)

Return a cost report for all Workspace usage, broken down by object and time.

Parameters

Returns

A list of BillingReportItem dataclasses. Each item reports the cost attributed to a specific Modal object during a given time interval. Cost is further broken down by the resource type that generated it (e.g. CPU, Memory, specific GPU usage). Note that the specific resource types included in the breakdown are subject to change as Modal's billing model evolves.

See Also

• modal billing report: A workspace report CLI that has convenience features around relative time range queries and JSON/CSV output.
• Environment.billing.report(): An analogous report API that is scoped to a specific Environment.

billing.summary

summary(self, cycle=None)

Return a summary of workspace cost over a single billing cycle determined by cycle

Parameters

Returns

A single WorkspaceBillingSummary dataclass containing the following fields:

• metered_cost representing cost before any adjustments,
• billed_cost representing the cost actually invoiced, including all adjustments,
• adjustments containing a breakdown of the adjustments that make up the difference between metered_cost and billed_cost. This can include discounts for free volume storage, adjustments due to plan credits, etc. The exact keys of this are subject to change as Modal's billing model evolves.
• metered_cost_breakdown containing a breakdown of that cost by the Modal resources that generated it. The exact keys of this are subject to change as Modal's billing model evolves.

All values are reported as decimal.Decimals.

See Also

• modal billing summary: A workspace summary CLI that has convenience features around relative time range queries.
• Environment.billing.summary(): An analogous summary API that is scoped to a specific Environment.

proxy_tokens

proxy_tokens: WorkspaceProxyTokenManager

Namespace with methods for managing the proxy tokens in a Workspace.

See the guide for more information on proxy tokens.

proxy_tokens.create

create(self)

Create a new proxy token for the Workspace.

Usage

token = modal.Workspace.from_context().proxy_tokens.create()
print(token.token_id, token.token_secret)

proxy_tokens.list

list(self, environment_name=None)

List proxy tokens in the Workspace.

Parameters

Usage

ws = modal.Workspace.from_context()

# List all proxy tokens in the Workspace
tokens = ws.proxy_tokens.list()
print([t.token_id for t in tokens])

# List only the proxy tokens associated with a specific Environment
env_tokens = ws.proxy_tokens.list(environment_name="prod")

proxy_tokens.allow

allow(self, proxy_token_id, environment_name)

Allow a proxy token to authenticate requests to a given Environment.

Parameters

Usage

ws = modal.Workspace.from_context()
token = ws.proxy_tokens.create()
ws.proxy_tokens.allow(token.token_id, "prod")

proxy_tokens.revoke

revoke(self, proxy_token_id, environment_name)

Revoke a proxy token's access to a given Environment.

The proxy token is not deleted, and it will continue to authenticate requests to any other Environments it is associated with.

Parameters

Usage

ws = modal.Workspace.from_context()
ws.proxy_tokens.revoke(token_id, "prod")

proxy_tokens.delete

delete(self, proxy_token_id)

Delete a proxy token from the Workspace.

This cannot be reverted. Any clients currently using the token will immediately lose access to associated resources.

Parameters

Usage

modal.Workspace.from_context().proxy_tokens.delete(token_id)

settings

settings: WorkspaceSettingsManager

Namespace for Workspace settings APIs.

settings.valid_settings

valid_settings(cls)

settings.list

list(self)

Return a the current workspace settings.

Returns

A WorkspaceSettings dataclass.

settings.set

set(self, name, value)

Set a workspace setting to a new value. Must be workspace manager or owner.

The following settings can be updated:

• image-builder-version: The image builder version determines the software included in our base images.
• default-environment: The default environment when the environment is omitted from SDK or CLI methods.

Parameters

Usage

modal.Workspace.from_context().settings.set("default-environment", "dev")