---
title: "Change a project's editor machine type, sandbox environment or idle shutdown"
method: PATCH
path: "/projects/{projectId}/machine"
tags: ["Machines"]
---

# Change a project's editor machine type, sandbox environment or idle shutdown

`PATCH /projects/{projectId}/machine`

## Request

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

Changes the machine type, sandbox environment or idle shutdown of the project machine. A new idle shutdown applies right away; a stopped machine picks up the other changes on its next start. A running machine needs `restart: true`, otherwise the request returns 409 and changes nothing. If the restarted machine cannot start, the request returns 409 but keeps the change. A custom machine type only runs in its own sandbox environment, so moving off it needs a new `type`. To run a single detached run or session on another machine type, pass `machineType` when creating it.

## Path parameters

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

## Request body

- object: At least one of `type`, `idleShutdownSeconds` or `sandboxEnvironmentId` is required.
  - `type` string: Machine type for the project, as an `id` from `GET /machine-types`.
  - `idleShutdownSeconds` integer: How long the machine keeps running without activity before it shuts down, in seconds, up to 24 hours.
  - `sandboxEnvironmentId` string: Sandbox environment to run the project in, as an `id` from `GET /machine-types`.
  - `restart` boolean: Restart a running machine so the change takes effect. Kernel state, such as variables, is lost.

## Response `200`

Updated project machine

- 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, the machine is running without `restart`, the plan does not allow the machine type, the sandbox environment is offline, or the restarted machine cannot start
- `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 `200`
  - the response property `machine/sandboxEnvironmentId` became nullable for the status `200`
  - response property `machine/error` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`
  - response property `machine/sandboxEnvironmentId` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`
- **2026-10-01** `df3d4eb06bcf`: 1 info
  - added the required property `machine/startingPhase` to the response with the `200` status
- **2026-09-30** `72a433c3cd28`: 2 info
  - added the new optional request property `sandboxEnvironmentId`
  - added the required property `machine/sandboxEnvironmentId` to the response with the `200` status
- **2026-09-29** `349de235eff0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/deepnote/apis/deepnote-public-api/changes/projects/:projectId/machine/patch.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)