Run notebooks using API

This page describes API requests used to run Datalore notebooks and get status on completed runs.

Run a notebook

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.

Get a run status

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

Run a notebook in interactive mode

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.

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

Error responses

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

Error code	Details
400	You provided an incorrect query.
401	No token or invalid token was specified.
403	You only have view rights to this notebook.
404	The notebook is not shared with you, or you specified an invalid notebook ID.

Keywords

running options, running API, Datalore API

Last modified: 11 July 2024