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

Runs the notebook with the given ID and returns the run ID.

Request template

POST /api/run/v1/notebook

Request parameters

Type	Parameter	Details
Header	Authorization: Bearer {token}	`{token}` is an API token value that can be found in Datalore at Account settings \| API tokens.
Header	Content-Type: application/json	Specifies the request content type.
Body (JSON)	"notebookId": {user_id/notebook_id}	`{user_id/notebook_id}` is a string that you can select from the notebook URL: `https://datalore.jetbrains.com/notebook/{user_id/notebook_id}`.
Body (JSON)	"updateReport": "on success"	(Optional) Updates the associated report if the run was successful. Datalore ignores this setting if no report has been published. Default is `never`.
Body (JSON)	"directFileStorageWrite": true	(Optional) Saves run data to notebook files instead of isolated artifact storage. Default is `false`. This setting corresponds to the Run data isolation parameter in the UI.

Response JSON object

Parameter	Details
"runId"	Returns the ID of the executed run.

Get a run status

Returns the status of the run with the given ID.

Request template

GET /api/run/v1/{runId}

Request parameters

Type	Parameter	Details
Path	`{runId}`	Specifies the run ID.
Header	`Authorization: Bearer {token}`	`{token}` is an API token value that can be found in Datalore at Account settings \| API tokens.

Response JSON object

The response JSON object contains the following fields describing the specified run.

Parameter	Details
`"runId"`	Run ID
`"userId"`	Notebook user ID
`"notebookId"`	Notebook ID
`"startTime"`	Run start time
`"endTime"`	Run end time
`"success"`	Run success status (`true`/`false`)
`"status"`	Current status of the run (only present while the run is in progress)
`"updateReport"`	Report update setting (`on success`/`never`)
`"directFileStorageWrite"`	If `true`, the run results were saved to the notebook files, not a dedicated run artifact directory.
"artifacts": [ { "name": "{notebook_name}", "path": "{notebook_path}" } ]	Notebook file name (with .ipynb extension) Path to the notebook file
`"readOnly"`	Notebook access type: `true` for viewer access, `false` for editor access

Run a notebook in interactive mode

The request runs a notebook specified by its ID interactively. This updates the notebook outputs in place.

Request template

POST /api/computation/v1/notebook

Request parameters

Type	Parameter	Details
Header	`Authorization: Bearer {token}`	`{token}` is an API token value that can be found in Datalore at Account settings \| API tokens.
Header	`Content-Type: application/json`	Specifies the request content type.
Body (JSON)	`"notebookId": {user_id/notebook_id}`	`{user_id/notebook_id}` is a string that you can select from the notebook URL: https://datalore.jetbrains.com/notebook/{user_id/notebook_id}/.

Response JSON object

Running notebooks interactively does not return run ID or artifacts; it only updates the notebook outputs.

Run a notebook with parameters

The request starts a parameterized run using values from the interactive controls in the notebook.

Request template

POST /api/run/v1/notebook

Request parameters

Type	Parameter	Details
Header	`Authorization: Bearer {token}`	`{token}` is an API token value that can be found in Datalore at Account settings \| API tokens.
Header	`Content-Type: application/json`	Specifies the request content type.
Body (JSON)	`"notebookId": {user_id/notebook_id}`	`{user_id/notebook_id}` is a string that you can select from the notebook URL: https://datalore.jetbrains.com/notebook/{user_id/notebook_id}/.
Body (JSON)	`"updateReport": "on success"`	Optional. Updates the associated report if the run was successful; ignored if no report was published. By default, set to `never`.
Body (JSON)	"directFileStorageWrite": true	(Optional) Saves run data to notebook files instead of isolated artifact storage. Default is `false`. This setting corresponds to the Run data isolation parameter in the UI.
Body (JSON)	`"parameters": [{"name": "variable_name", "value": "variable_value"}]`	`name` is the `Variable` value from the interactive control settings. For example, `Columns` is the variable used for the `name` parameter.

Response JSON object

Parameter	Details
`"runId"`	Returns the ID of the executed run.

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
    

Error responses

The following table lists error responses for Datalore API requests.

Error code	Details
`400`	The request is malformed or contains invalid parameters.
`401`	No token was provided, or the token is invalid.
`403`	You have view-only access to this notebook.
`404`	The notebook is not shared with you, or the notebook ID is invalid.

06 May 2026