Run a Jupyter Notebook

POST /api/v1.2/commands

Use this API to run a Jupyter notebook. You can view the command’s status, result, or cancel a command using the corresponding Command API that are used for other types of command.

Required Role

The following users can make this API call:

  • Users who belong to the system-user or system-admin group.
  • Users who belong to a group associated with a role that allows update on Jupyter Notebook and directory. See Managing Groups and Managing Roles for more information.



Parameters marked in bold below are mandatory. Others are optional and have default values.

Parameter Description
path Path including name of the Jupyter notebook to be run with extension (.ipynb).
label Label of the cluster on which the Jupyter notebook should be run. If this parameter is not specified then label = “default” is used.
command_type Type of command to be executed. For Jupyter notebook, the command type is JupyterNotebookCommand.

Valid JSON to be sent to the notebook. Specify the parameters in notebooks and pass the parameter value using the JSON format. key is the parameter’s name and value is the parameter’s value.

Supported types in parameters are string, integer, float, and boolean.

Request API Syntax

Here is the Request API syntax for running a Jupyter notebook.

curl  -i -X POST -H "X-AUTH-TOKEN: <auth_token>" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"path":"<Path>/<Name>”, "command_type":"JupyterNotebookCommand",  "label":"<ClusterLabel>", "arguments": {"key1":"value1", "key2":"value2", ..., "keyN":"valueN"}}' \

Sample API Request

curl  -i -X POST -H "X-AUTH-TOKEN: $AUTH_TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"path":"Users/[email protected]/note1.ipynb”, "command_type":"JupyterNotebookCommand",  "label":"spark-cluster-1", "arguments": {"name":"xyz", "age":"20"}}' \

Known Limitation

If there is a warning in one of the cells when this API is run, the notebook stops executing at that cell. As a workaround, to skip the warning and continue execution, add raises-exception in that cell’s metadata field by performing the following steps:

  1. Select the cell that shows the warning.
  2. Click on the Tools icon on the left side bar.
  3. Click Advanced Tools.
  4. Add raises-exception in the Cell Metadata tags field.
  5. Re-run the API.