Managing machines with the Deepnote API

Every project has a machine that powers its editor, its live runs and its hosted Streamlit apps. The API lets you control that machine from your own tools: have it running before people need it, upgrade it for a heavy job, and switch it off so it stops using machine hours.

Detached runs and interactive sessions start machines of their own, so you do not need to start the project machine for them.

In a project that runs privately, the editor and live runs use each person's own machine. GET, start, stop and restart act on the machine of whoever calls them. PATCH changes the project's settings, which a person's machine picks up the next time it starts; its restart option and its 409 refer to the project's shared machine. Hosted Streamlit apps stay on the project's machine.

All examples use $DEEPNOTE_TOKEN; see Authentication.

Check a machine

curl -s "https://api.deepnote.com/v2/projects/$PROJECT_ID/machine" \
  -H "Authorization: Bearer $DEEPNOTE_TOKEN"

{
  "machine": {
    "status": "running",
    "error": null,
    "startingPhase": null,
    "type": {
      "id": "fjord",
      "name": "CPU (Plus)",
      "type": "deepnote",
      "vCpus": 4,
      "memoryGiB": 16,
      "gpuCount": 0,
      "sandboxEnvironmentId": null
    },
    "sandboxEnvironmentId": "deepnote",
    "idleShutdownSeconds": 900
  }
}

status is stopped, starting, running, stopping or error. While a machine starts, startingPhase says whether it is waiting_for_capacity or pulling_image. The endpoint is cheap enough to poll.

Start, stop and restart

curl -s -X POST "https://api.deepnote.com/v2/projects/$PROJECT_ID/machine/start" \
  -H "Authorization: Bearer $DEEPNOTE_TOKEN"

start and stop are safe to repeat. restart is not: every call replaces whatever machine is running, so a retried restart replaces the machine the previous one just started, and everyone's variables are lost again. If a restart request times out, poll GET …/machine instead of retrying it. A 409 explains what is in the way. From restart, a 409 for a suspended project means nothing changed. Any other 409 comes after the old machine was stopped: if the new one could not start yet, wait and call start; a plan's machine limit or disabled pay-as-you-go has to be resolved first, and calling start again will not help until it is.

Change the hardware or idle shutdown

GET /v2/machine-types lists the machine types and sandbox environments your workspace can use, with their CPUs, memory and GPUs, and whether each is available on your plan.

curl -s -X PATCH "https://api.deepnote.com/v2/projects/$PROJECT_ID/machine" \
  -H "Authorization: Bearer $DEEPNOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "<machine-type-id>", "idleShutdownSeconds": 3600, "restart": true }'

• idleShutdownSeconds (up to 24 hours) applies immediately to the project's machine. In a project that runs privately, a person's machine picks it up the next time it starts.
• type and sandboxEnvironmentId apply on the machine's next start. A running machine needs "restart": true; without it the request returns 409 and changes nothing. Restarting loses the kernel's variables. If the restarted machine cannot start, the request returns 409 but keeps the change.
• To use bigger hardware for a single job without changing the project, pass machineType to a run or session instead.

Recipes

• Ready before people arrive. A scheduled job calls start at 08:45 on weekdays, so the first person to open a heavy project does not wait for it to boot or for its init notebook to install packages.
• Off when nobody is working. A nightly job lists projects with GET /v2/projects, checks each machine and calls stop on those still running. Set a short idleShutdownSeconds on projects that do not need to stay warm.
• Bigger hardware for crunch time. Switch a project to a GPU or high-memory type before a training sprint, and back afterwards, from the same script.
• Self-healing. A monitor that sees error calls restart once and polls until running, rather than retrying the restart; on a 409 saying the new machine could not start yet, it waits and calls start, and on any other 409 it alerts someone.

Related

• Selecting hardware and Machine hours
• Long-running jobs
• Deepnote API and the API reference