Datalore 2024.4 Help

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.

Slider settings
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