Llm API Reference

Llm

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`POST`
`POST`
`POST`
`POST`
`POST`
`POST`
`GET`
`POST`
`GET`

← Previous pageNext page →

List all llm analytics score definitions

Required API key scopes

llm_analytics:read

Query parameters

archived
boolean
kind
string
limit
integer
offset
integer
order_by
string
search
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "kind": "categorical",
      "archived": true,
      "current_version": 0,
      "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
      "config": {
        "options": [
          {
            "key": "string",
            "label": "string"
          }
        ],
        "selection_mode": "single",
        "min_selections": 1,
        "max_selections": 1
      },
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "team": 0
    }
  ]
}

List all llm analytics score definitions

Required API key scopes

llm_analytics:read

Query parameters

archived
boolean
kind
string
limit
integer
offset
integer
order_by
string
search
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "kind": "categorical",
      "archived": true,
      "current_version": 0,
      "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
      "config": {
        "options": [
          {
            "key": "string",
            "label": "string"
          }
        ],
        "selection_mode": "single",
        "min_selections": 1,
        "max_selections": 1
      },
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "team": 0
    }
  ]
}

Create llm analytics score definitions

Required API key scopes

llm_analytics:write

Request parameters

name
string
description
stringnull
kind
archived
boolean
Default: false
config

Response

Example request

POST /api/environments/:project_id/llm_analytics/score_definitions
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/environments/:project_id/llm_analytics/score_definitions/\
	-d name="string",\
	-d kind=undefined,\
	-d config=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Create llm analytics score definitions

Required API key scopes

llm_analytics:write

Request parameters

name
string
description
stringnull
kind
archived
boolean
Default: false
config

Response

Example request

POST /api/environments/:project_id/llm_analytics/score_definitions
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/environments/:project_id/llm_analytics/score_definitions/\
	-d name="string",\
	-d kind=undefined,\
	-d config=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Retrieve llm analytics score definitions

Required API key scopes

llm_analytics:read

Path parameters

id
string

Response

Example request

GET /api/environments/:project_id/llm_analytics/score_definitions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/llm_analytics/score_definitions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/{llm_analytics-5_id}/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Retrieve llm analytics score definitions

Required API key scopes

llm_analytics:read

Path parameters

id
string

Response

Example request

GET /api/environments/:project_id/llm_analytics/score_definitions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/llm_analytics/score_definitions/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/{llm_analytics-5_id}/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Update llm analytics score definitions

Required API key scopes

llm_analytics:write

Path parameters

id
string

Request parameters

name
string
description
stringnull
archived
boolean

Response

Example request

PATCH /api/environments/:project_id/llm_analytics/score_definitions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/llm_analytics/score_definitions/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/{llm_analytics-5_id}/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Update llm analytics score definitions

Required API key scopes

llm_analytics:write

Path parameters

id
string

Request parameters

name
string
description
stringnull
archived
boolean

Response

Example request

PATCH /api/environments/:project_id/llm_analytics/score_definitions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/llm_analytics/score_definitions/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/{llm_analytics-5_id}/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Create llm analytics score definitions new version

Required API key scopes

llm_analytics:write

Path parameters

id
string

Request parameters

config
base_version
integer

Response

Example request

POST /api/environments/:project_id/llm_analytics/score_definitions/:id/new_version
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/environments/:project_id/llm_analytics/score_definitions/:id/new_version/\
	-d config=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/{llm_analytics-5_id}/new_version/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Create llm analytics score definitions new version

Required API key scopes

llm_analytics:write

Path parameters

id
string

Request parameters

config
base_version
integer

Response

Example request

POST /api/environments/:project_id/llm_analytics/score_definitions/:id/new_version
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/environments/:project_id/llm_analytics/score_definitions/:id/new_version/\
	-d config=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/score_definitions/{llm_analytics-5_id}/new_version/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "kind": "categorical",
  "archived": true,
  "current_version": 0,
  "current_version_id": "158beffb-f9de-457f-bbee-873740e72504",
  "config": {
    "options": [
      {
        "key": "string",
        "label": "string"
      }
    ],
    "selection_mode": "single",
    "min_selections": 1,
    "max_selections": 1
  },
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "team": 0
}

Create llm analytics sentiment

Required API key scopes

llm_analytics:write

Request parameters

ids
array
analysis_level
Default: trace
force_refresh
boolean
Default: false
date_from
stringnull
date_to
stringnull

Response

Example request

POST /api/environments/:project_id/llm_analytics/sentiment
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/environments/:project_id/llm_analytics/sentiment/\
	-d ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/sentiment/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ids": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "results": {
    "property1": {
      "label": "string",
      "score": 0.1,
      "scores": {
        "property1": 0.1,
        "property2": 0.1
      },
      "messages": {
        "property1": {
          "label": "string",
          "score": 0.1,
          "scores": {
            "property1": 0.1,
            "property2": 0.1
          }
        },
        "property2": {
          "label": "string",
          "score": 0.1,
          "scores": {
            "property1": 0.1,
            "property2": 0.1
          }
        }
      },
      "message_count": 0
    },
    "property2": {
      "label": "string",
      "score": 0.1,
      "scores": {
        "property1": 0.1,
        "property2": 0.1
      },
      "messages": {
        "property1": {
          "label": "string",
          "score": 0.1,
          "scores": {
            "property1": 0.1,
            "property2": 0.1
          }
        },
        "property2": {
          "label": "string",
          "score": 0.1,
          "scores": {
            "property1": 0.1,
            "property2": 0.1
          }
        }
      },
      "message_count": 0
    }
  }
}

Status 400

Status 500

Create llm analytics sentiment generations

Request parameters

filters

Response

Example request

POST /api/environments/:project_id/llm_analytics/sentiment/generations
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/environments/:project_id/llm_analytics/sentiment/generations/\
	-d filters=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/sentiment/generations/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "results": [
    [
      null
    ]
  ]
}

Status 400

Status 500

Create llm analytics summarization

Generate an AI-powered summary of an LLM trace or event.

This endpoint analyzes the provided trace/event, generates a line-numbered text representation, and uses an LLM to create a concise summary with line references.

Two ways to use this endpoint:

By ID (recommended): Pass trace_id or generation_id with an optional date_from/date_to. The backend fetches the data automatically. summarize_type is inferred.
By data: Pass the full trace/event data blob in data with summarize_type. This is how the frontend uses it.

Summary Format:

Title (concise, max 10 words)
Mermaid flow diagram showing the main flow
3-10 summary bullets with line references
"Interesting Notes" section for failures, successes, or unusual patterns
Line references in [L45] or [L45-52] format pointing to relevant sections

The response includes the structured summary, the text representation, and metadata.

Required API key scopes

llm_analytics:write

Request parameters

summarize_type
mode
Default: minimal
data
force_refresh
boolean
Default: false
model
stringnull
trace_id
string
generation_id
string
date_from
stringnull
date_to
stringnull

Response

Example request

POST /api/environments/:project_id/llm_analytics/summarization
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/environments/:project_id/llm_analytics/summarization/\
	-d summarize_type=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/summarization/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "summary": "## Summary\n- User initiated conversation with greeting [L5-8]\n- Assistant responded with friendly message [L12-15]\n\n## Interesting Notes\n- Standard greeting pattern with no errors",
  "metadata": {
    "text_repr_length": 450,
    "model": "gpt-4.1"
  }
}

Status 400

Status 403

Status 500

Create llm analytics summarization batch check

Check which traces have cached summaries available.

This endpoint allows batch checking of multiple trace IDs to see which ones have cached summaries. Returns only the traces that have cached summaries with their titles.

Use Cases:

Load cached summaries on session view load
Avoid unnecessary LLM calls for already-summarized traces
Display summary previews without generating new summaries

Request parameters

trace_ids
array
mode
Default: minimal
model
stringnull

Response

Example request

POST /api/environments/:project_id/llm_analytics/summarization/batch_check
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/environments/:project_id/llm_analytics/summarization/batch_check/\
	-d trace_ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/summarization/batch_check/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"trace_ids": "array"
	}
).json()

Example response

Status 200

RESPONSE
{
  "summaries": [
    {
      "trace_id": "string",
      "title": "string",
      "cached": true
    }
  ]
}

Status 400

Status 403

Create llm analytics text repr

Generate a human-readable text representation of an LLM trace event.

This endpoint converts AI observability events ($ai_generation, $ai_span, $ai_embedding, or $ai_trace) into formatted text representations suitable for display, logging, or analysis.

Supported Event Types:

$ai_generation: Individual LLM API calls with input/output messages
$ai_span: Logical spans with state transitions
$ai_embedding: Embedding generation events (text input → vector)
$ai_trace: Full traces with hierarchical structure

Options:

max_length: Maximum character count (default: 2000000)
truncated: Enable middle-content truncation within events (default: true)
truncate_buffer: Characters at start/end when truncating (default: 1000)
include_markers: Use interactive markers vs plain text indicators (default: true)
- Frontend: set true for <<<TRUNCATED|base64|...>>> markers
- Backend/LLM: set false for ... (X chars truncated) ... text
collapsed: Show summary vs full trace tree (default: false)
include_hierarchy: Include tree structure for traces (default: true)
max_depth: Maximum depth for hierarchical rendering (default: unlimited)
tools_collapse_threshold: Number of tools before auto-collapsing list (default: 5)
- Tool lists >5 items show <<<TOOLS_EXPANDABLE|...>>> marker for frontend
- Or [+] AVAILABLE TOOLS: N for backend when include_markers: false
include_line_numbers: Prefix each line with line number like L001:, L010: (default: false)

Use Cases:

Frontend display: truncated: true, include_markers: true, include_line_numbers: true
Backend LLM context (summary): truncated: true, include_markers: false, collapsed: true
Backend LLM context (full): truncated: false

The response includes the formatted text and metadata about the rendering.

Required API key scopes

llm_analytics:write

Request parameters

event_type
data
options

Response

Example request

POST /api/environments/:project_id/llm_analytics/text_repr
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/environments/:project_id/llm_analytics/text_repr/\
	-d event_type=undefined,\
	-d data=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/text_repr/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "text": "INPUT:\n\n[1] USER\n\nWhat is the capital of France?\n\n...",
  "metadata": {
    "event_type": "$ai_generation",
    "event_id": "gen_123",
    "rendering": "detailed",
    "char_count": 150,
    "truncated": false
  }
}

Status 400

Status 500

Status 503

List all llm analytics trace reviews

Required API key scopes

llm_analytics:read

Query parameters

definition_id
string
definition_id__in
string
limit
integer
offset
integer
order_by
string
search
string
trace_id
string
trace_id__in
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "trace_id": "string",
      "trace_url": "http://example.com",
      "comment": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "reviewed_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "scores": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "definition_id": "91c1994f-b1db-4fef-840d-7d3ab2984871",
          "definition_name": "string",
          "definition_kind": "string",
          "definition_archived": true,
          "definition_version_id": "3b4c7def-d68b-4f5f-846c-43f0f8a328ab",
          "definition_version": 0,
          "definition_config": {
            "options": [
              {
                "key": "string",
                "label": "string"
              }
            ],
            "selection_mode": "single",
            "min_selections": 1,
            "max_selections": 1
          },
          "categorical_values": [
            "string"
          ],
          "numeric_value": "string",
          "boolean_value": true,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "team": 0
    }
  ]
}

List all llm analytics trace reviews

Required API key scopes

llm_analytics:read

Query parameters

definition_id
string
definition_id__in
string
limit
integer
offset
integer
order_by
string
search
string
trace_id
string
trace_id__in
string

Response

Example request

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

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "trace_id": "string",
      "trace_url": "http://example.com",
      "comment": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "reviewed_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "scores": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "definition_id": "91c1994f-b1db-4fef-840d-7d3ab2984871",
          "definition_name": "string",
          "definition_kind": "string",
          "definition_archived": true,
          "definition_version_id": "3b4c7def-d68b-4f5f-846c-43f0f8a328ab",
          "definition_version": 0,
          "definition_config": {
            "options": [
              {
                "key": "string",
                "label": "string"
              }
            ],
            "selection_mode": "single",
            "min_selections": 1,
            "max_selections": 1
          },
          "categorical_values": [
            "string"
          ],
          "numeric_value": "string",
          "boolean_value": true,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "team": 0
    }
  ]
}

Create llm analytics trace reviews

Required API key scopes

llm_analytics:write

Request parameters

trace_id
string
comment
stringnull
scores
array
queue_id
stringnull

Response

Example request

POST /api/environments/:project_id/llm_analytics/trace_reviews
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/environments/:project_id/llm_analytics/trace_reviews/\
	-d trace_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/trace_reviews/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"trace_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "trace_id": "string",
  "trace_url": "http://example.com",
  "comment": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "reviewed_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "scores": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "definition_id": "91c1994f-b1db-4fef-840d-7d3ab2984871",
      "definition_name": "string",
      "definition_kind": "string",
      "definition_archived": true,
      "definition_version_id": "3b4c7def-d68b-4f5f-846c-43f0f8a328ab",
      "definition_version": 0,
      "definition_config": {
        "options": [
          {
            "key": "string",
            "label": "string"
          }
        ],
        "selection_mode": "single",
        "min_selections": 1,
        "max_selections": 1
      },
      "categorical_values": [
        "string"
      ],
      "numeric_value": "string",
      "boolean_value": true,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "team": 0
}

Create llm analytics trace reviews

Required API key scopes

llm_analytics:write

Request parameters

trace_id
string
comment
stringnull
scores
array
queue_id
stringnull

Response

Example request

POST /api/environments/:project_id/llm_analytics/trace_reviews
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/environments/:project_id/llm_analytics/trace_reviews/\
	-d trace_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/trace_reviews/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"trace_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "trace_id": "string",
  "trace_url": "http://example.com",
  "comment": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "reviewed_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "scores": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "definition_id": "91c1994f-b1db-4fef-840d-7d3ab2984871",
      "definition_name": "string",
      "definition_kind": "string",
      "definition_archived": true,
      "definition_version_id": "3b4c7def-d68b-4f5f-846c-43f0f8a328ab",
      "definition_version": 0,
      "definition_config": {
        "options": [
          {
            "key": "string",
            "label": "string"
          }
        ],
        "selection_mode": "single",
        "min_selections": 1,
        "max_selections": 1
      },
      "categorical_values": [
        "string"
      ],
      "numeric_value": "string",
      "boolean_value": true,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "team": 0
}

Retrieve llm analytics trace reviews

Required API key scopes

llm_analytics:read

Path parameters

id
string

Response

Example request

GET /api/environments/:project_id/llm_analytics/trace_reviews/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/environments/:project_id/llm_analytics/trace_reviews/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/environments/{project_id}/llm_analytics/trace_reviews/{llm_analytics-5_id}/".format(
        project_id=project_id,
		llm_analytics-5_id="<the llm analytics-5 id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "trace_id": "string",
  "trace_url": "http://example.com",
  "comment": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "reviewed_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "scores": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "definition_id": "91c1994f-b1db-4fef-840d-7d3ab2984871",
      "definition_name": "string",
      "definition_kind": "string",
      "definition_archived": true,
      "definition_version_id": "3b4c7def-d68b-4f5f-846c-43f0f8a328ab",
      "definition_version": 0,
      "definition_config": {
        "options": [
          {
            "key": "string",
            "label": "string"
          }
        ],
        "selection_mode": "single",
        "min_selections": 1,
        "max_selections": 1
      },
      "categorical_values": [
        "string"
      ],
      "numeric_value": "string",
      "boolean_value": true,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "team": 0
}

← Previous pageNext page →