Run notebooks using API

The Datalore Run API lets you trigger notebook runs programmatically and check their execution status. Use it to automate workflows, integrate notebook execution into external systems, or run notebooks on a schedule.

Run a notebook

/api/run/v1/notebook

Runs the notebook with the given ID and returns the run ID. Optionally accepts parameters for parameterized runs using values from the interactive controls in the notebook.

Request parameters

{
  "notebookId": "user123/notebook456",
  "updateReport": "never",
  "directFileStorageWrite": true,
  "parameters": [
    {
      "name": "Columns",
      "value": "revenue"
    }
  ]
}

Responses

{
  "runId": "example"
}

Get a run status

/api/run/v1/{runId}

Returns the status of the run with the given ID.

Request parameters

Responses

{
  "runId": "example",
  "userId": "example",
  "notebookId": "example",
  "startTime": "1971-04-26T12:26:06Z",
  "endTime": "1971-04-26T12:26:06Z",
  "success": true,
  "status": "example",
  "updateReport": "never",
  "directFileStorageWrite": true,
  "artifacts": [
    {
      "name": "analysis.ipynb",
      "path": "/notebook/user123/notebook456/artifacts/run1/analysis.ipynb"
    }
  ],
  "readOnly": true
}

Run a notebook in interactive mode

/api/computation/v1/notebook

Runs the notebook specified by its ID interactively. This updates the notebook outputs in place. Does not return a run ID or artifacts.

Request parameters

{
  "notebookId": "user123/notebook456"
}

Responses

Run API commands from a notebook

You can run API commands directly from a notebook in the Datalore editor to trigger another notebook. The following example shows a one-cell notebook containing API requests.

HOST = "https://datalore.jetbrains.com"
API_TOKEN = "my-api-token"
NOTEBOOK_ID = "my-user/my-notebook" # make sure it's not the CURRENT notebook if you don't want infinite recursion

import requests
import time
from IPython.display import display, HTML
from urllib.parse import quote

response = requests.post(
  f"{HOST}/api/run/v1/notebook",
  headers={"Authorization": f"Bearer {API_TOKEN}"},
  json={"notebookId": NOTEBOOK_ID, "updateReport": "never"}
)
print('Submit response: ', response)
if not response.ok:
  raise RuntimeError("Error submitting request")
else:
  run_id = response.json()["runId"]

hasEndTime = False
while not hasEndTime:
  status_response = requests.get(
    f"{HOST}/api/run/v1/{run_id}",
    headers={"Authorization": f"Bearer {API_TOKEN}"}
  )
  run = status_response.json()
  if run.get('endTime'):
    hasEndTime = True
    print('Finished')
    print(status_response.json())
  else:
    print('Status: ', run.get('status'))
    time.sleep(1)

artifacts = {}
for artifact in status_response.json()['artifacts']:
  display(HTML(f"<a href='{artifact['path']}'>{artifact['name']}</a>"))
  artifacts[artifact['name']] = requests.get(
    f"{HOST}{quote(artifact['path'])}",
    headers={"Authorization": f"Bearer {API_TOKEN}"}
  ).text

artifacts
    

15 May 2026