Notebooks API Reference

Notebooks

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`POST`
`POST`
`GET`
`POST`
`POST`
`GET`
`POST`
`GET`
`GET`
`GET`

← Previous page

Create notebooks kernel restart

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

short_id
string

Request parameters

title
stringnull
content
text_content
stringnull
version
integer
deleted
boolean
_create_in_folder
string

Example request

POST /api/projects/:project_id/notebooks/:short_id/kernel/restart
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/kernel/restart/\
	-d title=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/kernel/restart/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"title": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200 No response body

Create notebooks kernel start

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

short_id
string

Request parameters

title
stringnull
content
text_content
stringnull
version
integer
deleted
boolean
_create_in_folder
string

Example request

POST /api/projects/:project_id/notebooks/:short_id/kernel/start
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/kernel/start/\
	-d title=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/kernel/start/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"title": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200 No response body

Retrieve notebooks kernel status

Live-checked kernel runtime state for this notebook, its compute configuration, and the catalog of dataframes/tables a cell can currently reference (with column schemas).

Required API key scopes

notebook:read

Path parameters

short_id
string

Response

Example request

GET /api/projects/:project_id/notebooks/:short_id/kernel/status
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/kernel/status/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/kernel/status/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "backend": "string",
  "status": "string",
  "last_used_at": "2019-08-24T14:15:22Z",
  "last_error": "string",
  "runtime_id": "cb6c5dda-251e-4b64-ab75-e6c8247ffa87",
  "kernel_id": "string",
  "kernel_pid": 0,
  "sandbox_id": "string",
  "frames": [
    {
      "name": "string",
      "kind": "string",
      "columns": [
        [
          "string"
        ]
      ],
      "row_count": 0,
      "row_count_is_estimate": false
    }
  ],
  "cpu_cores": 0.1,
  "memory_gb": 0.1,
  "disk_size_gb": 0,
  "idle_timeout_seconds": 0
}

Create notebooks kernel stop

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Path parameters

short_id
string

Request parameters

title
stringnull
content
text_content
stringnull
version
integer
deleted
boolean
_create_in_folder
string

Example request

POST /api/projects/:project_id/notebooks/:short_id/kernel/stop
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/kernel/stop/\
	-d title=["string","null"]
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/kernel/stop/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"title": [
			"string",
			"null"
		]
	}
).json()

Example response

Status 200 No response body

Create notebooks sql v2 run

Dispatch an asynchronous run of a notebook SQL or Python cell. Returns a run_id immediately; poll the run result endpoint until the status is terminal. Flag-gated (revamped-py-notebooks).

Required API key scopes

notebook:writequery:read

Path parameters

short_id
string

Request parameters

node_id
string
node_type
Default: hogql
code
string
output_name
string
Default:
refs
object
connection_id
stringnull
send_raw_query
boolean
Default: false

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/sql_v2/run
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/sql_v2/run/\
	-d node_id="string",\
	-d code="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/sql_v2/run/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"node_id": "string",
		"code": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec"
}

Retrieve notebooks sql v2 runs

Read a run's durable state: its status, and — once done or interrupted — the result envelope (columns, first rows, stdout/stderr, media, error). Poll until terminal. Flag-gated (revamped-py-notebooks).

Required API key scopes

notebook:readquery:read

Path parameters

run_id
string
short_id
string

Response

Example request

GET /api/projects/:project_id/notebooks/:short_id/sql_v2/runs/:run_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/sql_v2/runs/:run_id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/sql_v2/runs/{run_id}/".format(
        project_id=project_id,
		run_id="<the run id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "status": "string",
  "result": {
    "status": "string",
    "frames": [
      {
        "name": "string",
        "kind": "string",
        "columns": [
          [
            "string"
          ]
        ],
        "row_count": 0,
        "row_count_is_estimate": false
      }
    ],
    "stdout": "",
    "stderr": "",
    "media": [
      {
        "mime_type": "string",
        "data": "string"
      }
    ],
    "columns": [
      "string"
    ],
    "types": [
      [
        "string"
      ]
    ],
    "row_count": 0,
    "has_more": false,
    "first_page": [
      [
        null
      ]
    ],
    "result_id": "cd1ea384-5045-47f3-9678-d1fc6f8c8581",
    "error": "string",
    "timings": {
      "property1": 0.1,
      "property2": 0.1
    }
  },
  "error": "string",
  "rows": [
    [
      null
    ]
  ]
}

Create notebooks sql v2 runs interrupt

Stop a running cell. Idempotent: interrupting an already-finished run returns its outcome unchanged. Flag-gated (revamped-py-notebooks).

Required API key scopes

notebook:write

Path parameters

run_id
string
short_id
string

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/sql_v2/runs/:run_id/interrupt
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/sql_v2/runs/:run_id/interrupt/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/sql_v2/runs/{run_id}/interrupt/".format(
        project_id=project_id,
		run_id="<the run id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "status": "string",
  "detail": "string"
}

Status 202

RESPONSE
{
  "status": "string",
  "detail": "string"
}

Retrieve notebooks sql v2 state

The full notebook view for agents: title, document source (markdown, or raw content for legacy rich-text notebooks), every cell with its dependency edges and derived run status (including staleness), and the kernel's runtime state and compute config. Flag-gated (revamped-py-notebooks).

Required API key scopes

notebook:readquery:read

Path parameters

short_id
string

Response

Example request

GET /api/projects/:project_id/notebooks/:short_id/sql_v2/state
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/:short_id/sql_v2/state/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/sql_v2/state/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "notebook_id": "string",
  "title": "string",
  "version": 0,
  "markdown": "string",
  "content": null,
  "kernel": {
    "status": "string",
    "cpu_cores": 0,
    "memory_gb": 0,
    "idle_timeout_seconds": 0
  },
  "cells": [
    {
      "node_id": "string",
      "cell_type": "string",
      "dataframe_name": "string",
      "code": "string",
      "status": "string",
      "depends_on": [
        "string"
      ],
      "dependents": [
        "string"
      ],
      "last_run": {
        "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
        "status": "string",
        "finished_at": "2019-08-24T14:15:22Z",
        "row_count": 0,
        "columns": [
          "string"
        ],
        "error": "string"
      }
    }
  ]
}

Retrieve notebooks all activity

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Example request

GET /api/projects/:project_id/notebooks/activity
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/activity/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/activity/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

Retrieve notebooks recording comments

The API for interacting with Notebooks. This feature is in early access and the API can have breaking changes without announcement.

Example request

GET /api/projects/:project_id/notebooks/recording_comments
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/notebooks/recording_comments/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/recording_comments/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 No response body

← Previous page