> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a notebook

> Create an inline SQL notebook, open its SQL kernel session, execute a cell, read outputs, and close the session. The notebook service and SQL kernel must be enabled.

How-to guideApplies to: Unified engine deployments

Create an inline SQL notebook, open its SQL kernel session, execute a cell, read outputs, and close the session. The notebook service and SQL kernel must be enabled.

### Run an inline SQL notebook

Create a saved notebook, open a SQL session, run its cell, inspect outputs, then close its session.

| Placeholder | Value |
| - | - |
| `{{create_submission}}` | A new UUID for this request; reuse it when recovering the same submission. |
| `{{session_submission}}` | A new UUID for this request; reuse it when recovering the same submission. |
| `{{run_submission}}` | A new UUID for this request; reuse it when recovering the same submission. |

Replace the placeholders in your client. Keep returned IDs for later requests. Paths below use the native API prefix; adjust it for your deployment.

#### 1. Create a SQL notebook

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/notebooks
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{create_submission}}",
  "name": "HTTP example - orders notebook",
  "document": {
    "nbformat": 4,
    "nbformat_minor": 5,
    "metadata": {
      "kernelspec": {
        "name": "sql",
        "display_name": "SQL",
        "language": "sql"
      }
    },
    "cells": [
      {
        "cell_type": "code",
        "id": "orders-summary",
        "metadata": {},
        "source": "WITH orders(id, category, region, amount) AS (VALUES (1, 'Books', 'North', 20), (2, 'Games', 'South', 30), (3, 'Games', 'North', 15), (4, 'Books', 'North', 40), (5, 'Garden', 'South', 25), (6, 'Garden', 'North', 10)) SELECT category, SUM(amount) AS sales FROM orders GROUP BY category ORDER BY category",
        "execution_count": null,
        "outputs": []
      }
    ]
  },
  "settings": {
    "query": {
      "current_catalog": "default",
      "namespace": [
        "default"
      ],
      "time_zone": "UTC",
      "case_sensitive": false,
      "ansi_enabled": true
    },
    "options": {
      "execution_target": "DuckDb"
    }
  }
}
```

From the response, keep `notebook_id` from `/notebook/notebook_id`, `notebook_revision` from `/notebook/revision`.

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/create-notebook.md).

#### 2. Open the SQL kernel

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/notebooks/{{notebook_id}}/sessions
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{session_submission}}",
  "kernel_name": "sql"
}
```

From the response, keep `notebook_session` from `/session/session_id`.

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/open-notebook-session.md).

#### 3. Run the notebook

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /api/v1/notebooks/{{notebook_id}}/runs
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{run_submission}}",
  "session_id": "{{notebook_session}}",
  "expected_revision": {{notebook_revision}}
}
```

From the response, keep `notebook_run` from `/run/run_id`.

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/submit-notebook-run.md).

#### 4. Follow cell execution

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /api/v1/notebooks/{{notebook_id}}/runs/{{notebook_run}}
Host: <ENGINE_HOST>
```

From the response, keep `execution_id` from `/run/cells/0/execution_id`.

Repeat this read until `/run/status` reaches a terminal state: `Succeeded`, `Failed`, `Cancelled`, `OutcomeUnknown`, `Skipped`.

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/get-notebook-run.md).

#### 5. Read cell outputs

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /api/v1/notebooks/{{notebook_id}}/runs/{{notebook_run}}/cells/{{execution_id}}/outputs
Host: <ENGINE_HOST>
```

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/notebook-outputs.md).

#### 6. Close the notebook session

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
DELETE /api/v1/notebooks/{{notebook_id}}/sessions/{{notebook_session}}
Host: <ENGINE_HOST>
```

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/close-notebook-session.md).

The document follows the notebook JSON format. Creation returns a notebook identity and revision. Session creation returns a notebook session identity, which is different from an interactive SQL session ID.

Follow the notebook run. Read the returned cell execution IDs before requesting cell outputs or events; a document cell ID is not an execution ID. The sample query should return three category totals: Books 60, Games 45, and Garden 35.

Close the notebook session after execution finishes. Keep or delete the saved notebook using its current revision. If you export it, choose whether outputs should be included; retained outputs can make the export much larger.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.