---
title: "Stop a project's editor machine"
method: POST
path: "/projects/{projectId}/machine/stop"
tags: ["Machines"]
---

# Stop a project's editor machine

`POST /projects/{projectId}/machine/stop`

## Request

- Base URL: `https://api.deepnote.com/v2`
- URL: `https://api.deepnote.com/v2/projects/{projectId}/machine/stop`
- Auth: HTTP bearer

Stops the project machine so it no longer uses machine time. Kernel state, such as variables, is lost for everyone working in the project; files in the project are kept. Stopping a machine that is not running does nothing and succeeds. This is the machine the editor, live-mode runs and hosted Streamlit apps use; machines of detached runs and interactive sessions keep running. Stop a session with `DELETE /sessions/{sessionId}`.

## Path parameters

- `projectId` string, uuid, required: ID of the project whose machine to use.

## Response `202`

Machine stop accepted

- MachineResponse
  - `machine` Machine, required: The project's machine: the one the editor, live-mode runs and hosted Streamlit apps use. Detached runs and interactive sessions run on machines of their own and are not reflected here.
    - `status` 'stopped' | 'starting' | 'running' | 'stopping' | 'error', required: `stopped`: no machine is running; start it with `POST /projects/{projectId}/machine/start`. `starting`: the machine is booting, or is briefly unreachable; `startingPhase` says what it is waiting for. Poll until it is `running`. `running`: the machine is ready to run code. `stopping`: the machine is shutting down; wait for `stopped` before starting it again. `error`: the machine failed to start or stopped working, see `error`; fix the cause, then restart it with `POST /projects/{projectId}/machine/restart`.
    - `error` string, nullable, required: Why the machine is in the `error` status. Null for every other status.
    - `startingPhase` 'waiting_for_capacity' | 'pulling_image', required: `waiting_for_capacity`: no node has room for the machine yet, and the cluster may be adding one. `pulling_image`: the machine's image is being downloaded onto its node, which can take several minutes for a large image on a new node.
    - `type` MachineTypeSpecs, required
      - `id` string, required: Machine type identifier: a Deepnote machine type such as `fjord`, or `custom:<machine-id>` for a custom machine of the workspace.
      - `name` string, required
      - `type` 'deepnote' | 'custom', required: `deepnote` for machine types Deepnote provides, `custom` for machines the workspace defined in one of its sandbox environments. A project can only use a custom machine when it runs in that sandbox environment.
      - `vCpus` number, required: Number of vCPUs the machine can use.
      - `memoryGiB` number, required: Memory the machine can use, in GiB.
      - `gpuCount` integer, required: Number of GPUs attached to the machine.
      - `sandboxEnvironmentId` string, uuid, nullable, required: Sandbox environment a custom machine belongs to. Null for Deepnote machine types.
    - `sandboxEnvironmentId` string, nullable, required: Sandbox environment the machine runs in; see `GET /machine-types`. Null when the caller cannot view it.
    - `idleShutdownSeconds` integer, required: How long the machine keeps running without activity before it shuts down, in seconds.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Insufficient permissions
- `404`: Project not found
- `409`: Project is suspended
- `429`: Rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-10-28** `062f5f1b4638`: 2 breaking, 2 info
  - the response property `machine/error` became nullable for the status `202`
  - the response property `machine/sandboxEnvironmentId` became nullable for the status `202`
  - response property `machine/error` list-of-types was narrowed by removing types `null` from media type `application/json` of response `202`
  - response property `machine/sandboxEnvironmentId` list-of-types was narrowed by removing types `null` from media type `application/json` of response `202`
- **2026-10-01** `df3d4eb06bcf`: 1 info
  - added the required property `machine/startingPhase` to the response with the `202` status
- **2026-09-30** `72a433c3cd28`: 1 info
  - added the required property `machine/sandboxEnvironmentId` to the response with the `202` status
- **2026-09-29** `349de235eff0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/deepnote/apis/deepnote-public-api/changes/projects/:projectId/machine/stop/post.md)

---

[API](https://skmtc.dev/deepnote/apis/deepnote-public-api.md) - [All operations](https://skmtc.dev/deepnote/apis/deepnote-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/deepnote/apis/deepnote-public-api/revisions/b081f9aea3dc?raw)