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 .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 .- 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 .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 .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 theVariable
value from the interactive control settings. For example,Columns
is the variable used for thename
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.
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