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}/logs/streamIssue a session log stream
Issues a short-lived token and URL for streaming the session's Sail server log from the customer-side session proxy. Worker pods in cluster mode are not exposed. Returns 409 while the session's pod is not yet running (retry shortly) or when the cluster requires re-provisioning for live logs; 410 when the session's resources have been cleaned up.
Responses
Responses
Connection details for the session's live log stream.
/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.