Interactive compute sessions, lifecycle management, and token issuance.
/workloads/sessionsList sessions
Returns sessions visible to the caller: sessions they own plus sessions belonging to teams they are a member of. Passing teamId narrows the list to that team.
Parameters
teamIdstring
Filter sessions by team.
"A1B2C3D4E5"120"^[A-Z0-9]{1,20}$"endpoint_typestring
Filter sessions by endpoint type.
"spark_connect""marimo"statusstring
Filter sessions by status.
"pending""active""idle""closed""failed"limitinteger
The maximum number of items to list.
"int32"0100100markerstring
The pagination token returned from the previous list operation.
Responses
Responses
The list of sessions.
/workloads/sessionsCreate a session
Creates a new session. Resolves or creates a compute config, finds a reusable compute instance or provisions a new one, and returns the session in pending state. The session transitions to active on the first proxy request after the compute instance is ready.
Request Body
Responses
Responses
The session was created successfully.
/workloads/sessions/{session}Describe a session
Returns the session details. For the session owner, includes connectionInfo with the proxy authentication URL (HTTP-transport endpoints) or gRPC endpoint (gRPC-transport endpoints).
Responses
Responses
The session was retrieved successfully.
/workloads/sessions/{session}Close a session
Closes the session immediately. The session transitions to closed and closed_at is set. Infrastructure cleanup (marimo pod, compute instance) is handled asynchronously. Can be called by the session owner, team admin, or org admin.
Responses
Responses
The session was closed successfully.
/workloads/sessions/{session}/tokenIssue a session proxy token
Issues a short-lived signed JWT bearer token for authenticating with the session gRPC proxy. Use the grpcEndpoint from the session's connectionInfo as the dial address and pass the token as Authorization: Bearer
Request Body
Responses
Responses
A bearer token for gRPC proxy access.
/workloads/sessions/{session}/relaunchRelaunch a closed session
Creates a new session using the same workload configuration as a previously closed or failed session. Useful for restarting a recurring session without having to reconfigure compute settings from scratch.
The original session must be in a terminal state (closed or failed). A brand-new session ID is returned — the original session is not mutated. The caller must be the original session owner.
Responses
Responses
The session was relaunched successfully.
/workloads/sessions/{session}/destroyDestroy a session's compute infrastructure
Re-runs teardown of the session's compute infrastructure when a previous automatic teardown failed and the workload is stuck in cleanup_failed (for example, the compute cluster was temporarily unreachable). The teardown is re-attempted asynchronously.
When force is true, the failed teardown is instead abandoned: the workload is marked as needing manual cleanup (cleanup_abandoned_at is set) and removed from the user's active view. This does NOT delete the namespace in the customer cluster — the caller acknowledges they will remove it themselves. Use only when the infrastructure is unrecoverable.
Can be called by the session owner, team admin, or org admin.
Request Body
Responses
Responses
The teardown was re-attempted, or the workload was abandoned.
/workloads/configsList workload configs
Returns workload configs visible to the caller. When teamId is provided, only workload configs whose cluster is linked to that team are returned. Anonymous (inline) configs are excluded.
Parameters
teamIdstring
Filter workload configs by team.
"A1B2C3D4E5"120"^[A-Z0-9]{1,20}$"limitinteger
The maximum number of items to list.
"int32"0100100markerstring
The pagination token returned from the previous list operation.
Responses
Responses
The list of workload configs.
/workloads/configsCreate a workload config
Creates a named workload config for a cluster. Named configs can be reused across multiple sessions and shared with team members. Once created, workloadType and clusterId are immutable.
Request Body
Responses
Responses
The workload config was created successfully.
/workloads/configs/{workloadConfig}Describe a workload config
Returns the full detail of a workload config.
Responses
Responses
The workload config was retrieved successfully.
/workloads/configs/{workloadConfig}Delete a workload config
Deletes a workload config. The config is removed from listings and can no longer be referenced by new jobs, sessions, or notebooks. Existing workloads that already reference it keep working and retain their billing record.
Responses
Responses
The requested operation was done successfully.
/workloads/configs/{workloadConfig}Update a workload config
Updates a workload config's mutable fields (name, compute config, endpoint limits, and catalogs). workloadType and clusterId are immutable. Editing is billing-safe: past workloads bill from their own immutable compute snapshot, so changes only affect future workloads.
Request Body
Responses
Responses
The workload config was updated successfully.
/workloads/configs/{workloadConfig}/referencesGet workload config references
Returns the resources that currently reference a workload config. Notebooks and jobs are durable references that prevent deletion until repointed. Active workloads block deletion while they still depend on workload config resources such as secrets or catalogs.
Responses
Responses
The workload config references were retrieved successfully.