Deepnote Public API v2
Sessions API
Long-lived interactive sessions for running notebooks and blocks.
Base URL
https://api.deepnote.com/v2Create an interactive session
Creates an interactive session that runs the specified notebook and stays alive to accept further submissions. The session executes its own copy of the notebook (see `sessionNotebookId`); edit that copy via the standard notebook and block endpoints to change what subsequent runs execute — the source notebook is never modified. The session ends after a period of inactivity.
/sessionsRequest body
objectnotebookIdrequiredstringID of the source notebook the session is anchored to.
inputsobjectInput values for the initial run, keyed by input block `name`. Same shape as `POST /v2/runs`.
storageMode"read_write" | "readonly"Storage mode for the session. `read_write` (default) allows the session to write to project storage. `readonly` makes project storage read-only for the session; the session can still create temporary files.
Responses
▸202Session created with initial run
CreateSessionResponsesessionrequiredSessionrunrequiredobject▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Hardware unable to start
ErrorResponsemessagerequiredstringStop an interactive session
Stops all active runs in the session, initiates the shutdown of its machine, and ends the session. A stopped session cannot accept further submissions; stopping an already-stopped session returns 404. Only the session creator may stop the session.
/sessions/{sessionId}Parameters
sessionIdpathrequiredstring:uuidSession identifier.
Responses
▸204Session stopped
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Session not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstringExecute arbitrary code in a session kernel (debug)
Runs arbitrary code inside the notebook's kernel within an interactive session and returns the raw outputs (without creating a snapshot). User-code exceptions are returned as error outputs inside the response body and still produce HTTP 200. Only the session creator may execute code, and doing so requires edit access to the project, the same as editing blocks.
/sessions/{sessionId}/executeParameters
sessionIdpathrequiredstring:uuidSession identifier.
Request body
objectnotebookIdrequiredstringSource notebook to execute against in the session. Use the session's source notebook ID (`session.notebookId`), not `sessionNotebookId`.
coderequiredstringSource code to execute in the session sandbox.
timeoutMsintegerMaximum execution time in milliseconds. Must be a positive integer no greater than 120000. Values outside this range are rejected with 400; the server does not clamp. Defaults to 10000 when omitted.
Responses
▸200Outputs produced by the synchronous execution.
ExecuteSessionResponseoutputsrequiredJupyterOutput[]Raw Jupyter (nbformat) outputs produced by the synchronous execution. User-code exceptions are returned as `output_type: "error"` entries here, not as HTTP errors.
▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸408Execution timed out
ErrorResponsemessagerequiredstring▸409Project is suspended, the notebook is busy with a tracked run, or the session kernel is unavailable
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringInterrupt active runs for a notebook in an interactive session
Interrupts active runs for the given notebook in an interactive session and signals the notebook kernel to stop any in-flight code, including arbitrary code submitted via `/sessions/{sessionId}/execute`. Other notebooks in the same session keep running, so the session may remain `busy`. Returns the refreshed session state. Only the session creator may interrupt runs.
/sessions/{sessionId}/interruptParameters
sessionIdpathrequiredstring:uuidSession identifier.
Request body
objectnotebookIdrequiredstringNotebook to interrupt within the session. Use the session's source notebook ID (`session.notebookId`), not `sessionNotebookId`.
Responses
▸200Session state after the interrupt.
InterruptSessionResponsesessionrequiredSession▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringSubmit a run on an interactive session
Runs a notebook, or specific blocks of it, in an existing interactive session. Only the session creator may submit runs. Submissions while the notebook is busy are accepted and queue on the session kernel; retrying a submit creates a new queued run.
/sessions/{sessionId}/runsParameters
sessionIdpathrequiredstring:uuidSession identifier.
Request body
objectnotebookIdrequiredstringID of the notebook to run within the session. Use the session's source notebook ID (`session.notebookId`), not `sessionNotebookId`.
blockIdsstring[]Optional non-empty list of unique block IDs to run, in request order. Omit to run the whole notebook. Use session block IDs from the session's notebook copy (see `sessionNotebookId` on the session); source-notebook block IDs are rejected.
inputsobjectInput values to use for this run, keyed by the input `name` returned from `GET /notebooks/{sessionNotebookId}` (the session's editable copy, which the run resolves inputs against). Values must match the referenced input block type.
Responses
▸202Run accepted
CreateRunResponserunIdrequiredstring:uuidstatusrequired"pending" | "running" | "success" | "error" | "internal_error" | "stopped"createdAtrequiredstring:date-time▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring▸500Internal server error
ErrorResponsemessagerequiredstringGet kernel status for a notebook in an interactive session
Returns the current kernel state for a notebook in an interactive session, including the currently executing block and queued block executions when available. Each notebook in a session has its own kernel; name the notebook via the `notebookId` query parameter and query each notebook separately. Only the session creator may read the status.
/sessions/{sessionId}/statusParameters
sessionIdpathrequiredstring:uuidSession identifier.
notebookIdqueryrequiredstringNotebook within the session to read status for. Use the session's source notebook ID (`session.notebookId`), not `sessionNotebookId`.
Responses
▸200Current session and kernel status for the notebook.
GetSessionNotebookStatusResponsesessionrequiredSessionkernelrequiredSessionKernelState▸400Validation error
ErrorResponsemessagerequiredstring▸401Unauthorized
ErrorResponsemessagerequiredstring▸403Insufficient permissions
ErrorResponsemessagerequiredstring▸404Session or notebook not found
ErrorResponsemessagerequiredstring▸409Project is suspended
ErrorResponsemessagerequiredstring▸429Rate limit exceeded
ErrorResponsemessagerequiredstring