Interactive compute sessions, lifecycle management, and token issuance.
/workloads/sessionsList sessions
Returns sessions visible to the caller. Members see their own sessions; team admins see all sessions in their team; org admins see all sessions.
Parameters
teamIdstring
Filter sessions by team.
"A1B2C3D4E5"120"^[A-Z0-9]{1,20}$"endpoint_typestring
Filter sessions by endpoint type.
"spark_connect"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/compute-configsList workload configs
Returns workload configs visible to the caller. Org admins see all configs; team admins see configs belonging to their teams; members see configs for teams they belong to. 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/compute-configsCreate a workload config
Creates a named workload config for a team. Named configs can be reused across multiple sessions and shared with team members. Once created, workloadType, clusterId, and teamId are immutable.
Request Body
Responses
Responses
The workload config was created successfully.
/workloads/compute-configs/{workloadConfig}Describe a workload config
Returns the full detail of a workload config.
Responses
Responses
The workload config was retrieved successfully.