Run notebooks using API

The request runs a notebook specified by its ID and returns the ID of the run.

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.

Response JSON object

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

The request returns the status of a run specified by its 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 an array of values 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 (returned only while running)
"updateReport"	Report update setting (on success/never)
"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

The request runs a notebook specified by its ID interactively. This updates the notebook outputs where necessary.

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 artefacts; it only updates the notebook outputs.

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)	"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.

You can open a notebook in the Datalore editor and use API commands from there to run another notebook. Below is an example of 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

Below is the table describing error responses for Datalore API requests.

running options, running API, Datalore API