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.

blockIdsstring[]

Optional non-empty list of unique block IDs to run. Omit to run the full notebook. When provided without `runDependentBlocks`, only these blocks run, in request order.

runDependentBlocksboolean

When true and `blockIds` is provided, also run downstream blocks that depend on the selected blocks.

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
429Rate limit exceeded
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
429Rate limit exceeded
application/jsonErrorResponse
messagerequiredstring
500Internal server error
application/jsonErrorResponse
messagerequiredstring