Deepnote research: our notes on building agents
Get started
All endpoint groups

Deepnote Public API v2

Runs API

Notebook executions.

Base URL

https://api.deepnote.com/v2

Run a notebook

post/runs

Request body

required
application/jsonobject
notebookIdrequiredstring

ID of the notebook to run.

detachedboolean

Run the notebook as a detached run so it does not affect the live editor session.

detachedRunStorageMode"read_write" | "readonly"

Storage mode for the detached run. `read_write` (default) mounts project storage as writable; `readonly` mounts it as read-only so the run cannot modify the persistent project storage, but can create ephemeral files outside of the persistent project storage directory. Only applies to detached runs.

inputsobject

Input values to use for this run, keyed by the input `name` returned from `GET /notebooks/{notebookId}`. Values must match the referenced input block type.

Responses

▸202Run started
application/jsonCreateRunResponse
runIdrequiredstring:uuid
statusrequired"pending" | "running" | "success" | "error" | "internal_error" | "stopped"
createdAtrequiredstring:date-time
▸400Validation error or notebook/project issue
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸500Hardware unable to start
application/jsonErrorResponse
messagerequiredstring

Get a run

get/runs/{runId}

Parameters

runIdpathrequiredstring:uuid
snapshotDeliveryquery"inline" | "downloadUrl"

Controls how an available run snapshot is returned. Defaults to `downloadUrl`. Use `inline` to return `snapshotContent` directly.

Responses

▸200Run details
application/jsonGetRunResponse
runrequiredRun
▸400Validation error
application/jsonErrorResponse
messagerequiredstring
▸401Unauthorized
application/jsonErrorResponse
messagerequiredstring
▸403Insufficient permissions
application/jsonErrorResponse
messagerequiredstring
▸404Run not found
application/jsonErrorResponse
messagerequiredstring
▸409Project is suspended
application/jsonErrorResponse
messagerequiredstring
▸500Internal server error
application/jsonErrorResponse
messagerequiredstring