A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat(server): add GET /api/kernel/status endpoint (#9768)
Myles Scolnick8d6e540b590b
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.pyindex 9ab6385425..5dd775293b 100644--- a/marimo/_cli/development/commands.py+++ b/marimo/_cli/development/commands.py@@ -431,6 +431,7 @@ def _generate_server_api_schema() -> dict[str, Any]:models.InvokeAiToolRequest,models.InvokeAiToolResponse,models.InvokeFunctionRequest,+ models.KernelStatusResponse,models.ListDataSourceConnectionRequest,models.ListSecretKeysRequest,models.ListSQLTablesRequest,diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex 5372f43a85..3bb283ef8a 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -24,6 +24,7 @@ from marimo._server.models.models import (ExecuteScratchpadRequest,InstantiateNotebookRequest,InvokeFunctionRequest,+ KernelStatusResponse,ModelRequest,SuccessResponse,UpdateUIElementValuesRequest,@@ -31,6 +32,7 @@ from marimo._server.models.models import (from marimo._server.router import APIRouterfrom marimo._server.uvicorn_utils import close_uvicornfrom marimo._server.workspace import MarimoFileKey+from marimo._session.types import KernelStatefrom marimo._types.ids import ConsumerIdfrom marimo._utils.asyncio_utils import cancel_and_wait@@ -245,6 +247,46 @@ async def run_cell(return SuccessResponse()[email protected]("/status")+@requires("edit")+async def kernel_status(+ *,+ request: Request,+) -> KernelStatusResponse:+ """+ parameters:+ - in: header+ name: Marimo-Session-Id+ schema:+ type: string+ required: true+ responses:+ 200:+ description: Report whether the kernel is currently executing.+ `running` means at least one cell is queued or running;+ `idle` means the kernel is alive but not executing; `stopped`+ means the kernel process is not running.+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/KernelStatusResponse"+ """+ app_state = AppState(request)+ session = app_state.require_current_session()++ if session.kernel_state() in (+ KernelState.STOPPED,+ KernelState.NOT_STARTED,+ ):+ return KernelStatusResponse(state="stopped")++ is_running = any(+ notification.status in ("queued", "running")+ for notification in session.session_view.cell_notifications.values()+ )+ return KernelStatusResponse(state="running" if is_running else "idle")++@router.post("/execute", include_in_schema=False)@requires("edit")async def execute_code(diff --git a/marimo/_server/models/models.py b/marimo/_server/models/models.pyindex 8885e0f3ee..13811cae38 100644--- a/marimo/_server/models/models.py+++ b/marimo/_server/models/models.py@@ -232,6 +232,13 @@ class ErrorResponse(BaseResponse):message: str | None = None+class KernelStatusResponse(msgspec.Struct, rename="camel"):+ # `running`: at least one cell is queued or running.+ # `idle`: the kernel is alive but not executing.+ # `stopped`: the kernel process is not running (dead or not started).+ state: Literal["running", "idle", "stopped"]++class FormatCellsRequest(msgspec.Struct, rename="camel"):codes: dict[CellId_t, str]line_length: intdiff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex ebf37f230a..e4a5f66d68 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -2540,6 +2540,17 @@ components:- errortitle: KernelStartupErrorNotificationtype: object+ KernelStatusResponse:+ properties:+ state:+ enum:+ - idle+ - running+ - stopped+ required:+ - state+ title: KernelStatusResponse+ type: objectKeymapConfig:description: "Configuration for keymaps.\n\n **Keys.**\n\n - `preset`:\\ one of `\"default\"` or `\"vim\"`\n - `overrides`: a dict of keymap actions\@@ -6770,6 +6781,24 @@ paths:schema:$ref: '#/components/schemas/SuccessResponse'description: Shutdown the kernel+ /api/kernel/status:+ get:+ parameters:+ - in: header+ name: Marimo-Session-Id+ required: true+ schema:+ type: string+ responses:+ 200:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/KernelStatusResponse'+ description: Report whether the kernel is currently executing. `running`+ means at least one cell is queued or running; `idle` means the kernel+ is alive but not executing; `stopped` means the kernel process is not+ running./api/kernel/stdin:post:parameters:diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex 8c6ceca577..ac664dadc5 100644--- a/packages/openapi/src/api.ts+++ b/packages/openapi/src/api.ts@@ -2524,6 +2524,43 @@ export interface paths {patch?: never;trace?: never;};+ "/api/kernel/status": {+ parameters: {+ query?: never;+ header?: never;+ path?: never;+ cookie?: never;+ };+ get: {+ parameters: {+ query?: never;+ header: {+ "Marimo-Session-Id": string;+ };+ path?: never;+ cookie?: never;+ };+ requestBody?: never;+ responses: {+ /** @description Report whether the kernel is currently executing. `running` means at least one cell is queued or running; `idle` means the kernel is alive but not executing; `stopped` means the kernel process is not running. */+ 200: {+ headers: {+ [name: string]: unknown;+ };+ content: {+ "application/json": components["schemas"]["KernelStatusResponse"];+ };+ };+ };+ };+ put?: never;+ post?: never;+ delete?: never;+ options?: never;+ head?: never;+ patch?: never;+ trace?: never;+ };"/api/kernel/stdin": {parameters: {query?: never;@@ -4905,6 +4942,11 @@ export interface components {/** @enum {unknown} */op: "kernel-startup-error";};+ /** KernelStatusResponse */+ KernelStatusResponse: {+ /** @enum {unknown} */+ state: "idle" | "running" | "stopped";+ };/*** KeymapConfig* @description Configuration for keymaps.diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.pyindex 28c50cc664..39255e0c3a 100644--- a/tests/_server/api/endpoints/test_execution.py+++ b/tests/_server/api/endpoints/test_execution.py@@ -120,6 +120,41 @@ class TestExecutionRoutes_EditMode:assert response.headers["content-type"] == "application/json"assert "success" in response.json()+ @staticmethod+ @with_session(SESSION_ID)+ def test_kernel_status(client: TestClient) -> None:+ response = client.get("/api/kernel/status", headers=HEADERS)+ assert response.status_code == 200, response.text+ assert response.headers["content-type"] == "application/json"+ assert response.json()["state"] in ("running", "idle", "stopped")++ @staticmethod+ @with_session(SESSION_ID)+ def test_kernel_status_running(client: TestClient) -> None:+ from marimo._messaging.notification import CellNotification++ session = get_session_manager(client).get_session(SESSION_ID)+ assert session is not None+ # Seed a synthetic running cell the real kernel never emits, so a+ # concurrent idle broadcast for the notebook's own cells can't race+ # this assertion.+ session.session_view.cell_notifications[CellId_t("status-test")] = (+ CellNotification(cell_id=CellId_t("status-test"), status="running")+ )+ response = client.get("/api/kernel/status", headers=HEADERS)+ assert response.status_code == 200, response.text+ assert response.json()["state"] == "running"++ @staticmethod+ @with_session(SESSION_ID)+ def test_kernel_status_idle(client: TestClient) -> None:+ session = get_session_manager(client).get_session(SESSION_ID)+ assert session is not None+ session.session_view.cell_notifications.clear()+ response = client.get("/api/kernel/status", headers=HEADERS)+ assert response.status_code == 200, response.text+ assert response.json()["state"] == "idle"+@staticmethoddef test_restart_session(client: TestClient) -> None:with client.websocket_connect(@@ -438,6 +473,12 @@ class TestExecutionRoutes_RunMode:response = client.post("/api/kernel/interrupt", headers=HEADERS)assert response.status_code == 401, response.text+ @staticmethod+ @with_read_session(SESSION_ID)+ def test_kernel_status(client: TestClient) -> None:+ response = client.get("/api/kernel/status", headers=HEADERS)+ assert response.status_code == 401, response.text+@staticmethod@with_read_session(SESSION_ID)def test_restart_session(client: TestClient) -> None: