---
title: "Run a notebook"
method: POST
path: "/runs"
tags: ["Runs"]
---

# Run a notebook

`POST /runs`

## Request body

- object
  - `notebookId` string, required — ID of the notebook to run.
  - `detached` boolean — Run the notebook as a detached run so it does not affect the live editor session. Defaults to true; set to false to run in live mode and update outputs in the live app editor.
  - `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.
  - `blockIds` string[] — Optional non-empty list of unique block IDs to run. Only supported in live mode, so set `detached` to `false` when providing it. Omit to run the full notebook. When provided without `runDependentBlocks`, only these blocks run, in request order.
  - `runDependentBlocks` boolean — When true and `blockIds` is provided, also run downstream blocks that depend on the selected blocks.
  - `inputs` object — 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.

## Response `202`

Run started

- CreateRunResponse
  - `runId` string, uuid, required
  - `status` 'pending' | 'running' | 'success' | 'error' | 'internal_error' | 'stopped', required
  - `createdAt` string, date-time, required

## Other responses

- `400` — Validation error or notebook/project issue
- `401` — Unauthorized
- `403` — Insufficient permissions
- `429` — Rate limit exceeded
- `500` — Hardware unable to start

---

[API](https://skmtc.net/deepnote/apis/deepnote-public-api.md) · [All operations](https://skmtc.net/deepnote/apis/deepnote-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/deepnote/deepnote-public-api/revisions/726970fd2992/schema)