AI observability

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

Endpoints

GET
POST
GET
POST
POST
POST
POST

Retrieve ai observability traces summary

The trace's AI summary: pending while it is written, then ready with links to its steps, or failed with the reason. A summary is kept for an hour and shown only to users whose property access matches the requester's.

Required API key scopes

llm_analytics:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/ai_observability/traces/:id/summary
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/ai_observability/traces/:id/summary/

Example response

Status 200
RESPONSE
{
"status": "pending",
"content": {
"title": "string",
"bullets": [
{
"text": "string",
"nodeId": "string"
}
],
"notes": [
{
"text": "string",
"nodeId": "string"
}
],
"flow": "string",
"model": "string",
"generatedAt": "2019-08-24T14:15:22Z"
},
"failure": {
"reason": "trace_not_found",
"message": "string",
"retryable": true
}
}
Status 400 The encoded trace id is malformed.
Status 403 The organization has not approved AI data processing.
Status 404 No summary of this trace that this user may see.

Create ai observability traces summary

Request an AI summary of the trace. A ready summary is returned as is unless regenerate is set; otherwise a job starts writing one, or the request joins the job already writing it.

Required API key scopes

llm_analytics:write

Path parameters

  • id
    string

Query parameters

  • timestamp_hint
    string

Request parameters

  • regenerate
    boolean
    Default: false

Response


Example request

POST /api/projects/:project_id/ai_observability/traces/:id/summary
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/ai_observability/traces/:id/summary/\
-d regenerate="boolean"

Example response

Status 200 A ready or failed summary.
RESPONSE
{
"status": "pending",
"content": {
"title": "string",
"bullets": [
{
"text": "string",
"nodeId": "string"
}
],
"notes": [
{
"text": "string",
"nodeId": "string"
}
],
"flow": "string",
"model": "string",
"generatedAt": "2019-08-24T14:15:22Z"
},
"failure": {
"reason": "trace_not_found",
"message": "string",
"retryable": true
}
}
Status 202 The summary is being written.
RESPONSE
{
"status": "pending",
"content": {
"title": "string",
"bullets": [
{
"text": "string",
"nodeId": "string"
}
],
"notes": [
{
"text": "string",
"nodeId": "string"
}
],
"flow": "string",
"model": "string",
"generatedAt": "2019-08-24T14:15:22Z"
},
"failure": {
"reason": "trace_not_found",
"message": "string",
"retryable": true
}
}
Status 400 The timestamp hint or the encoded trace id is malformed.
Status 403 The organization has not approved AI data processing.
Status 429 Too many summaries requested.

Retrieve ai observability traces

A trace ready to render: its tree with roll-ups, timeline, totals and person, without inputs or outputs.

Required API key scopes

llm_analytics:read

Path parameters

  • id
    string

Query parameters

  • timestamp_hint
    string

Response


Example request

GET /api/projects/:project_id/ai_observability/traces/: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/ai_observability/traces/:id/

Example response

Status 200
RESPONSE
{
"id": "string",
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"sessionId": "string",
"totals": {
"costUsd": 0,
"inputTokens": 0,
"outputTokens": 0,
"cacheReadTokens": 0,
"cacheWriteTokens": 0,
"latencyMs": 0
},
"hasError": true,
"errorCount": 0,
"totalsPartial": true,
"person": {
"distinctId": "string",
"label": "string"
},
"tree": [
{
"id": "string",
"kind": "trace",
"name": "string",
"label": "string",
"model": "string",
"stats": {
"costUsd": 0,
"inputTokens": 0,
"outputTokens": 0,
"cacheReadTokens": 0,
"cacheWriteTokens": 0,
"latencyMs": 0
},
"hasError": true,
"children": [
{}
]
}
],
"timeline": [
{
"id": "string",
"kind": "trace",
"name": "string",
"depth": 0,
"startMs": 0,
"durationMs": 0,
"hasError": true
}
],
"totalMs": 0,
"threadNodeIds": [
"string"
],
"defaultNodeId": "string",
"nodeIdsByAlias": {
"property1": "string",
"property2": "string"
},
"git": {
"branch": "string",
"repo": "string"
}
}
Status 400 The timestamp hint or the encoded trace id is malformed.
Status 404 No trace with this id in the project.
Status 429 Too many queries are running for the project or organization.

Create ai observability traces availability

Required API key scopes

llm_analytics:read

Request parameters

  • trace_ids
    array

Response


Example request

POST /api/projects/:project_id/ai_observability/traces/availability
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/ai_observability/traces/availability/\
-d trace_ids="array"

Example response

Status 200
RESPONSE
{
"available_trace_ids": [
"string"
]
}
Status 429 Too many queries are running for the project or organization.

Create ai observability traces people

The person each trace on a page ran for, labeled by the project's display name properties.

Required API key scopes

llm_analytics:read

Request parameters

  • trace_ids
    array
  • earliest_created_at
    string
  • latest_created_at
    string

Response


Example request

POST /api/projects/:project_id/ai_observability/traces/people
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/ai_observability/traces/people/\
-d trace_ids="array",\
-d earliest_created_at="string",\
-d latest_created_at="string"

Example response

Status 200
RESPONSE
{
"items": [
{
"traceId": "string",
"person": {
"distinctId": "string",
"label": "string"
}
}
]
}
Status 400 The trace IDs or the page bounds are invalid.
Status 429 Too many queries are running for the project or organization.

Create ai observability traces previews

The input and output previews of a page of traces: the user's message each trace answered and its answer.

Required API key scopes

llm_analytics:read

Request parameters

  • trace_ids
    array

Response


Example request

POST /api/projects/:project_id/ai_observability/traces/previews
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/ai_observability/traces/previews/\
-d trace_ids="array"

Example response

Status 200
RESPONSE
{
"items": [
{
"traceId": "string",
"input": "string",
"output": "string",
"inputMissingReason": "too_large",
"outputMissingReason": "too_large"
}
]
}
Status 400 The trace IDs are missing or too many.
Status 429 Too many queries are running for the project or organization.

Create ai observability traces sentiment

The sentiment of each trace on a page, from its sentiment evaluation results.

Required API key scopes

llm_analytics:read

Request parameters

  • trace_ids
    array
  • earliest_created_at
    string
  • latest_created_at
    string

Response


Example request

POST /api/projects/:project_id/ai_observability/traces/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/projects/:project_id/ai_observability/traces/sentiment/\
-d trace_ids="array",\
-d earliest_created_at="string",\
-d latest_created_at="string"

Example response

Status 200
RESPONSE
{
"items": [
{
"traceId": "string",
"sentiment": {
"label": "positive",
"score": 0
}
}
]
}
Status 400 The trace IDs or the page bounds are invalid.
Status 429 Too many queries are running for the project or organization.