Notebooks

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

Endpoints

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

← Previous pageNext page →

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
string | null
content
text_content
string | null
version
integer
deleted
boolean
variables
array
_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"
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"
	}
).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,
  "hourly_price": 0.1,
  "preset_key": "string"
}

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
string | null
content
text_content
string | null
version
integer
deleted
boolean
variables
array
_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"
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"
	}
).json()

Example response

Status 200 No response body

Create notebooks runs

Run every SQL and Python cell of a markdown notebook, in document order, stopping at the first cell that does not finish. Returns as soon as the run starts; poll the run status 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

include_prepared_insights
boolean
Default: false
variables
array

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/runs
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/runs/\
	-d include_prepared_insights="boolean"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/runs/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"include_prepared_insights": "boolean"
	}
).json()

Example response

Status 200

RESPONSE
{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "cell_count": 0,
  "starts_sandbox": true,
  "sandbox_hourly_price": 0
}

Retrieve notebooks runs

Read a whole-notebook run: its state, which cell it is on, and one line per planned cell. Carries no result rows — fetch a cell's result from the cell run result endpoint. 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/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/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}/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
{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "status": "string",
  "trigger": "string",
  "variables": [
    {
      "name": "string",
      "type": "string",
      "value": null
    }
  ],
  "cell_count": 0,
  "current_index": 0,
  "current_node_id": "string",
  "failed_node_id": "string",
  "error": "string",
  "cells": [
    {
      "node_id": "string",
      "cell_type": "string",
      "dataframe_name": "string",
      "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
      "status": "string",
      "error": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "finished_at": "2019-08-24T14:15:22Z"
}

Create notebooks runs interrupt

Stop a whole-notebook run and the cell it is on. Idempotent: stopping a run that already finished 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/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/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}/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
{
  "interrupted": true,
  "status": "string"
}

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. One run at a time per notebook. Python notebooks enable all run types. Generated widgets enable HogQL runs without a connection or kernel.

Required API key scopes

notebook:writequery:read

Path parameters

short_id
string

Request parameters

reuse_results
boolean
Default: false
node_id
string
node_type
Default: hogql
code
string
output_name
string
Default:
refs
object
variables
array
connection_id
string | null
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",
  "starts_sandbox": true,
  "sandbox_hourly_price": 0
}

Status 409 The notebook already has a cell running. Wait for it to finish, then run this one. A conflict with the notebook's state rather than a rate, so it is not worth retrying on a timer.

Status 429 The project has as many notebook cells in flight as it may. Unlike the 409, retrying shortly is the right response.

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. Requires notebook and query read access, including after a notebook feature flag is disabled.

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"
      }
    ],
    "result_text": "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), the notebook's declared variables, 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
  },
  "variables": [
    {
      "name": "string",
      "type": "string",
      "value": null
    }
  ],
  "cells": [
    {
      "node_id": "string",
      "cell_type": "string",
      "dataframe_name": "string",
      "code": "string",
      "start": 0,
      "end": 0,
      "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"
      }
    }
  ]
}

Create notebooks widget snapshot

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

Required API key scopes

notebook:writequery:read

Path parameters

short_id
string

Request parameters

node_id
string
version_id
string
notebook_run_id
string
previous_snapshot_id
string

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/widget_snapshots
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/widget_snapshots/\
	-d node_id="string",\
	-d version_id="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}/widget_snapshots/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"node_id": "string",
		"version_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "node_id": "string",
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "created_at": "2019-08-24T14:15:22Z",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "artifact_url": "http://example.com",
  "build_hash": "string",
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  }
}

Status 400

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

Status 409

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

Retrieve notebooks widget snapshot

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

Required API key scopes

notebook:readquery:read

Path parameters

short_id
string
snapshot_id
string

Response

Example request

GET /api/projects/:project_id/notebooks/:short_id/widget_snapshots/:snapshot_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/widget_snapshots/:snapshot_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}/widget_snapshots/{snapshot_id}/".format(
        project_id=project_id,
		short_id="<the short id>",,
		snapshot_id="<the snapshot id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "node_id": "string",
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "created_at": "2019-08-24T14:15:22Z",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "artifact_url": "http://example.com",
  "build_hash": "string",
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  }
}

Retrieve notebooks widget snapshot

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

Required API key scopes

notebook:readquery:read

Path parameters

frame_name
string
short_id
string
snapshot_id
string

Query parameters

limit
integer
Default: 100
offset
integer
Default: 0
run_id
string
version_id
string

Response

Example request

GET /api/projects/:project_id/notebooks/:short_id/widget_snapshots/:snapshot_id/frames/:frame_name
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/widget_snapshots/:snapshot_id/frames/:frame_name/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/widget_snapshots/{snapshot_id}/frames/{frame_name}/".format(
        project_id=project_id,
		frame_name="<the frame name>",,
		short_id="<the short id>",,
		snapshot_id="<the snapshot id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "name": "string",
  "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "totalRowCount": 0,
  "includedRowCount": 0,
  "offset": 0,
  "nextOffset": 0,
  "truncated": true
}

Create notebooks widget snapshot

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

Required API key scopes

notebook:writequery:readdashboard:write

Path parameters

short_id
string

Request parameters

node_id
string
version_id
string
notebook_run_id
string
previous_snapshot_id
string
dashboard_id
integer
tile_id
integer
name
string
Default:

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/widget_snapshots/publish
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/widget_snapshots/publish/\
	-d node_id="string",\
	-d version_id="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}/widget_snapshots/publish/".format(
        project_id=project_id,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"node_id": "string",
		"version_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "node_id": "string",
  "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
  "created_at": "2019-08-24T14:15:22Z",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "artifact_url": "http://example.com",
  "build_hash": "string",
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  }
}

Status 400

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

Status 409

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

Create notebooks widget

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

Required API key scopes

notebook:write

Path parameters

node_id
string
short_id
string

Request parameters

widget_id
string
version_id
string | null
input_bindings
object

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/widgets/:node_id/attach
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/widgets/:node_id/attach/\
	-d widget_id="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}/widgets/{node_id}/attach/".format(
        project_id=project_id,
		node_id="<the node id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"widget_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "lifecycle_status": "awaiting_generation",
  "error_detail": "string",
  "error_code": "string",
  "failure_phase": "generating_source",
  "artifact_url": "http://example.com",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "pinned_version_id": "acdd174b-fedb-4cc2-a413-d2bf36fbaf58",
  "widget_id": "917f3fdb-2905-481f-8ff6-04c0fb7d466c",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "has_versions": true,
  "active_job": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "queued",
    "phase": "string",
    "model": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z"
  },
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  },
  "is_reusable": true,
  "build_hash": "string"
}

Status 400

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

Status 404

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

Status 409

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

Create notebooks widget

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

Required API key scopes

notebook:write

Path parameters

node_id
string
short_id
string

Request parameters

generation_id
string

Example request

POST /api/projects/:project_id/notebooks/:short_id/widgets/:node_id/cancel
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/widgets/:node_id/cancel/\
	-d generation_id="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}/widgets/{node_id}/cancel/".format(
        project_id=project_id,
		node_id="<the node id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"generation_id": "string"
	}
).json()

Example response

Status 204 No response body

Status 400

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

Status 404

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

Create notebooks widget

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

Required API key scopes

notebook:write

Path parameters

node_id
string
short_id
string

Request parameters

version_id
string | null

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/widgets/:node_id/fork
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/widgets/:node_id/fork/\
	-d version_id="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}/widgets/{node_id}/fork/".format(
        project_id=project_id,
		node_id="<the node id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"version_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "lifecycle_status": "awaiting_generation",
  "error_detail": "string",
  "error_code": "string",
  "failure_phase": "generating_source",
  "artifact_url": "http://example.com",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "pinned_version_id": "acdd174b-fedb-4cc2-a413-d2bf36fbaf58",
  "widget_id": "917f3fdb-2905-481f-8ff6-04c0fb7d466c",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "has_versions": true,
  "active_job": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "queued",
    "phase": "string",
    "model": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z"
  },
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  },
  "is_reusable": true,
  "build_hash": "string"
}

Status 400

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

Status 404

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

Status 409

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

Status 429

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

Retrieve notebooks widget

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

Required API key scopes

notebook:readquery:read

Path parameters

frame_name
string
node_id
string
short_id
string

Query parameters

limit
integer
offset
integer
run_id
string
version_id
string

Response

Example request

GET /api/projects/:project_id/notebooks/:short_id/widgets/:node_id/frames/:frame_name
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/widgets/:node_id/frames/:frame_name/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/notebooks/{short_id}/widgets/{node_id}/frames/{frame_name}/".format(
        project_id=project_id,
		frame_name="<the frame name>",,
		node_id="<the node id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "name": "string",
  "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  "columns": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "rows": [
    [
      null
    ]
  ],
  "totalRowCount": 0,
  "includedRowCount": 0,
  "offset": 0,
  "nextOffset": 0,
  "truncated": true
}

Status 403

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

Status 404

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

Status 409

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

Status 429

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

Create notebooks widget

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

Required API key scopes

notebook:writequery:read

Path parameters

node_id
string
short_id
string

Request parameters

prompt
string
generation_id
string
model
Default: claude-sonnet-5
generation_operation
Default: regenerate
expected_current_version_id
string

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/widgets/:node_id/generate
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/widgets/:node_id/generate/\
	-d prompt="string",\
	-d generation_id="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}/widgets/{node_id}/generate/".format(
        project_id=project_id,
		node_id="<the node id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"prompt": "string",
		"generation_id": "string"
	}
).json()

Example response

Status 202

RESPONSE
{
  "lifecycle_status": "awaiting_generation",
  "error_detail": "string",
  "error_code": "string",
  "failure_phase": "generating_source",
  "artifact_url": "http://example.com",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "pinned_version_id": "acdd174b-fedb-4cc2-a413-d2bf36fbaf58",
  "widget_id": "917f3fdb-2905-481f-8ff6-04c0fb7d466c",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "has_versions": true,
  "active_job": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "queued",
    "phase": "string",
    "model": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z"
  },
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  },
  "is_reusable": true,
  "build_hash": "string"
}

Status 400

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

Status 403

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

Status 404

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

Status 409

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

Status 429

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

Create notebooks widget

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

Required API key scopes

notebook:write

Path parameters

node_id
string
short_id
string

Request parameters

version_id
string | null

Response

Example request

POST /api/projects/:project_id/notebooks/:short_id/widgets/:node_id/pin
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/widgets/:node_id/pin/\
	-d version_id="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}/widgets/{node_id}/pin/".format(
        project_id=project_id,
		node_id="<the node id>",,
		short_id="<the short id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"version_id": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "lifecycle_status": "awaiting_generation",
  "error_detail": "string",
  "error_code": "string",
  "failure_phase": "generating_source",
  "artifact_url": "http://example.com",
  "frame_names": [
    "string"
  ],
  "input_bindings": {
    "property1": {
      "source": "string",
      "hog": "string"
    },
    "property2": {
      "source": "string",
      "hog": "string"
    }
  },
  "input_contract": [
    {
      "slot": "string",
      "sourceName": "string",
      "columns": [
        {
          "name": "string",
          "type": "string"
        }
      ],
      "schemaHash": "string"
    }
  ],
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "pinned_version_id": "acdd174b-fedb-4cc2-a413-d2bf36fbaf58",
  "widget_id": "917f3fdb-2905-481f-8ff6-04c0fb7d466c",
  "instance_id": "06587974-2dbe-4e10-8bf9-38cce0f5a366",
  "has_versions": true,
  "active_job": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "queued",
    "phase": "string",
    "model": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "started_at": "2019-08-24T14:15:22Z"
  },
  "security_review": {
    "severity": "none",
    "summary": "string",
    "findings": [
      {
        "severity": "low",
        "title": "string",
        "details": "string"
      }
    ],
    "model": "string",
    "review_version": "string",
    "reviewed_at": "2019-08-24T14:15:22Z"
  },
  "is_reusable": true,
  "build_hash": "string"
}

Status 400

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

Status 404

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

← Previous pageNext page →