Skip to content

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.

feat(server): add GET /api/kernel/status endpoint (#9768)

Myles Scolnick8d6e540b590b
diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.py
index 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.py
index 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 APIRouter
from marimo._server.uvicorn_utils import close_uvicorn
from marimo._server.workspace import MarimoFileKey
+from marimo._session.types import KernelState
from marimo._types.ids import ConsumerId
from marimo._utils.asyncio_utils import cancel_and_wait
@@ -245,6 +247,46 @@ async def run_cell(
return SuccessResponse()
+@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.py
index 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: int
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index ebf37f230a..e4a5f66d68 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -2540,6 +2540,17 @@ components:
- error
title: KernelStartupErrorNotification
type: object
+ KernelStatusResponse:
+ properties:
+ state:
+ enum:
+ - idle
+ - running
+ - stopped
+ required:
+ - state
+ title: KernelStatusResponse
+ type: object
KeymapConfig:
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.ts
index 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.py
index 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"
+
@staticmethod
def 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: