Llm

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

Endpoints

GET
GET
POST
GET
POST
GET
PATCH
DELETE
POST
GET
POST
GET
POST
GET
PATCH
DELETE
POST
GET
Next page →

List all llm analytics personal spend

Return a structured personal LLM spend analysis for the requesting user. Pass date_from / date_to (absolute like 2026-04-23 or relative like -7d) to bound the window — defaults to the last 30 days, max 90 days. The product=<ai_product> query param is required and scopes the tool / model / day / trace breakdowns to a single product; supported values: posthog_code. by_product is always returned for cross-product visibility. by_day returns a day-ascending spend series for the scoped product. Pass bucket_minutes (5, 15, 30, or 60; the window may span at most 600 buckets) to additionally get by_bucket, a time-ascending series with per-bucket cost split into uncached input / output / cache read / cache creation components. Use refresh=true to bypass the 5-minute response cache.

Required API key scopes

user:read

Query parameters

  • bucket_minutes
    integer
    One of: "5""15""30""60"
  • date_from
    string
    Default: -30d
  • date_to
    stringnull
  • limit
    integer
    Default: 50
  • product
    string
  • refresh
    boolean
    Default: false

Example request

GET /api/llm_analytics/@me/spend
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/llm_analytics/@me/spend/

Example response

Status 200
RESPONSE
{
  "summary": {
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z",
    "product": "string",
    "total_cost_usd": 0.1,
    "event_count": 0,
    "scoped_cost_usd": 0.1,
    "scoped_event_count": 0
  },
  "by_product": {
    "items": [
      {
        "product": "string",
        "event_count": 0,
        "cost_usd": 0.1
      }
    ],
    "truncated": true
  },
  "by_tool": {
    "items": [
      {
        "tool": "string",
        "generation_count": 0,
        "cost_usd": 0.1,
        "share_of_scoped": 0.1,
        "avg_input_tokens": 0.1
      }
    ],
    "truncated": true
  },
  "by_model": {
    "items": [
      {
        "model": "string",
        "generation_count": 0,
        "cost_usd": 0.1,
        "input_tokens": 0,
        "output_tokens": 0
      }
    ],
    "truncated": true
  },
  "by_day": {
    "items": [
      {
        "day": "2019-08-24",
        "event_count": 0,
        "cost_usd": 0.1
      }
    ],
    "truncated": true
  },
  "by_bucket": {
    "items": [
      {
        "bucket_start": "2019-08-24T14:15:22Z",
        "event_count": 0,
        "cost_usd": 0.1,
        "input_cost_usd": 0.1,
        "output_cost_usd": 0.1,
        "cache_read_cost_usd": 0.1,
        "cache_creation_cost_usd": 0.1,
        "input_tokens": 0,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ],
    "bucket_minutes": 0,
    "truncated": true
  },
  "top_traces": {
    "items": [
      {
        "trace_id": "string",
        "generation_count": 0,
        "cost_usd": 0.1,
        "started_at": "2019-08-24T14:15:22Z"
      }
    ],
    "truncated": true
  }
}
Status 400
RESPONSE
{
  "detail": "string"
}
Status 401
RESPONSE
{
  "detail": "string"
}
Status 403
RESPONSE
{
  "detail": "string"
}
Status 404
RESPONSE
{
  "detail": "string"
}
Status 429
RESPONSE
{
  "detail": "string"
}

List all llm analytics clustering config

Team-level clustering configuration (event filters for automated pipelines).

Required API key scopes

ai_observability_clusters:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "event_filters": [
    {}
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create llm analytics clustering config set event filters

Team-level clustering configuration (event filters for automated pipelines).

Required API key scopes

ai_observability_clusters:write

Request parameters

  • event_filters
    array

Response


Example request

POST /api/projects/:project_id/llm_analytics/clustering_config/set_event_filters
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/llm_analytics/clustering_config/set_event_filters/\
	-d event_filters="array"

Example response

Status 200
RESPONSE
{
  "event_filters": [
    {}
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

List all llm analytics clustering jobs

CRUD for clustering job configurations (max 10 per team).

Required API key scopes

ai_observability_clusters:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

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

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",
      "analysis_level": "trace",
      "event_filters": null,
      "enabled": true,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create llm analytics clustering jobs

CRUD for clustering job configurations (max 10 per team).

Required API key scopes

ai_observability_clusters:write

Request parameters

  • name
    string
  • analysis_level
  • event_filters
  • enabled
    boolean

Response


Example request

POST /api/projects/:project_id/llm_analytics/clustering_jobs
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/llm_analytics/clustering_jobs/\
	-d name="string",\
	-d analysis_level=undefined

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "analysis_level": "trace",
  "event_filters": null,
  "enabled": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve llm analytics clustering jobs

CRUD for clustering job configurations (max 10 per team).

Required API key scopes

ai_observability_clusters:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/llm_analytics/clustering_jobs/: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/llm_analytics/clustering_jobs/:id/

Example response

Status 200
RESPONSE

Update llm analytics clustering jobs

CRUD for clustering job configurations (max 10 per team).

Required API key scopes

ai_observability_clusters:write

Path parameters

  • id
    string

Request parameters

  • name
    string
  • analysis_level
  • event_filters
  • enabled
    boolean

Response


Example request

PATCH /api/projects/:project_id/llm_analytics/clustering_jobs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/llm_analytics/clustering_jobs/:id/\
	-d name="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "analysis_level": "trace",
  "event_filters": null,
  "enabled": true,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Delete llm analytics clustering jobs

CRUD for clustering job configurations (max 10 per team).

Required API key scopes

ai_observability_clusters:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/llm_analytics/clustering_jobs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/llm_analytics/clustering_jobs/:id/

Example response

Status 204 No response body

Create llm analytics clustering runs

Trigger a new clustering workflow run.

This endpoint validates the request parameters and starts a Temporal workflow to perform trace clustering with the specified configuration.

Required API key scopes

ai_observability_clusters:write

Request parameters

  • lookback_days
    integer
    Default: 7
  • max_samples
    integer
    Default: 1500
  • embedding_normalization
    Default: none
  • dimensionality_reduction_method
    Default: umap
  • dimensionality_reduction_ndims
    integer
    Default: 100
  • clustering_method
    Default: hdbscan
  • min_cluster_size_fraction
    number
    Default: 0.02
  • hdbscan_min_samples
    integer
    Default: 5
  • kmeans_min_k
    integer
    Default: 2
  • kmeans_max_k
    integer
    Default: 20
  • run_label
    string
    Default:
  • visualization_method
    Default: umap
  • event_filters
    array
  • clustering_job_id
    stringnull

Response


Example request

POST /api/projects/:project_id/llm_analytics/clustering_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/llm_analytics/clustering_runs/\
	-d lookback_days="integer"

Example response

Status 201
RESPONSE
{
  "lookback_days": 7,
  "max_samples": 1500,
  "embedding_normalization": "none",
  "dimensionality_reduction_method": "umap",
  "dimensionality_reduction_ndims": 100,
  "clustering_method": "hdbscan",
  "min_cluster_size_fraction": 0.02,
  "hdbscan_min_samples": 5,
  "kmeans_min_k": 2,
  "kmeans_max_k": 20,
  "run_label": "",
  "visualization_method": "umap",
  "event_filters": [
    {}
  ],
  "clustering_job_id": "5c6efd3e-fe43-4dec-9927-b4c0867e92ed"
}

Retrieve llm analytics evaluation config

Get the evaluation config for this team

Required API key scopes

evaluation:read

Response


Example request

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

Example response

Status 200
RESPONSE
{
  "active_provider_key": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "provider": "openai",
    "name": "string",
    "state": "unknown",
    "error_message": "string",
    "api_key": "string",
    "api_key_masked": "string",
    "azure_endpoint": "http://example.com",
    "api_version": "string",
    "azure_endpoint_display": "string",
    "api_version_display": "string",
    "set_as_active": false,
    "created_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"
    },
    "last_used_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create llm analytics evaluation config set active key

Set the active provider key for evaluations

Required API key scopes

evaluation:write

Request parameters

  • key_id
    string

Response


Example request

POST /api/projects/:project_id/llm_analytics/evaluation_config/set_active_key
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/llm_analytics/evaluation_config/set_active_key/\
	-d key_id="string"

Example response

Status 200
RESPONSE
{
  "active_provider_key": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "provider": "openai",
    "name": "string",
    "state": "unknown",
    "error_message": "string",
    "api_key": "string",
    "api_key_masked": "string",
    "azure_endpoint": "http://example.com",
    "api_version": "string",
    "azure_endpoint_display": "string",
    "api_version_display": "string",
    "set_as_active": false,
    "created_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"
    },
    "last_used_at": "2019-08-24T14:15:22Z"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

List all llm analytics evaluation reports

CRUD for evaluation report configurations + report run history.

Required API key scopes

llm_analytics:read

Query parameters

  • evaluation
    string
  • limit
    integer
  • offset
    integer

Response


Example request

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

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",
      "evaluation": "8b4883eb-9190-4e70-bfb9-71682af8a50b",
      "frequency": "scheduled",
      "rrule": "string",
      "starts_at": "2019-08-24T14:15:22Z",
      "timezone_name": "string",
      "next_delivery_date": "2019-08-24T14:15:22Z",
      "delivery_targets": null,
      "max_sample_size": -2147483648,
      "enabled": true,
      "deleted": true,
      "last_delivered_at": "2019-08-24T14:15:22Z",
      "report_prompt_guidance": "string",
      "trigger_threshold": 100,
      "cooldown_minutes": 60,
      "daily_run_cap": 1,
      "created_by": 0,
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create llm analytics evaluation reports

CRUD for evaluation report configurations + report run history.

Required API key scopes

llm_analytics:write

Request parameters

  • evaluation
    string
  • frequency
  • rrule
    string
  • delivery_targets
  • max_sample_size
    integer
  • enabled
    boolean
  • report_prompt_guidance
    string
  • trigger_threshold
    integernull
  • cooldown_minutes
    integer
  • daily_run_cap
    integer

Response


Example request

POST /api/projects/:project_id/llm_analytics/evaluation_reports
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/llm_analytics/evaluation_reports/\
	-d evaluation="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "evaluation": "8b4883eb-9190-4e70-bfb9-71682af8a50b",
  "frequency": "scheduled",
  "rrule": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "timezone_name": "string",
  "next_delivery_date": "2019-08-24T14:15:22Z",
  "delivery_targets": null,
  "max_sample_size": -2147483648,
  "enabled": true,
  "deleted": true,
  "last_delivered_at": "2019-08-24T14:15:22Z",
  "report_prompt_guidance": "string",
  "trigger_threshold": 100,
  "cooldown_minutes": 60,
  "daily_run_cap": 1,
  "created_by": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve llm analytics evaluation reports

CRUD for evaluation report configurations + report run history.

Required API key scopes

llm_analytics:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/llm_analytics/evaluation_reports/: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/llm_analytics/evaluation_reports/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "evaluation": "8b4883eb-9190-4e70-bfb9-71682af8a50b",
  "frequency": "scheduled",
  "rrule": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "timezone_name": "string",
  "next_delivery_date": "2019-08-24T14:15:22Z",
  "delivery_targets": null,
  "max_sample_size": -2147483648,
  "enabled": true,
  "deleted": true,
  "last_delivered_at": "2019-08-24T14:15:22Z",
  "report_prompt_guidance": "string",
  "trigger_threshold": 100,
  "cooldown_minutes": 60,
  "daily_run_cap": 1,
  "created_by": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Update llm analytics evaluation reports

CRUD for evaluation report configurations + report run history.

Required API key scopes

llm_analytics:write

Path parameters

  • id
    string

Request parameters

  • frequency
  • rrule
    string
  • delivery_targets
  • max_sample_size
    integer
  • enabled
    boolean
  • report_prompt_guidance
    string
  • trigger_threshold
    integernull
  • cooldown_minutes
    integer
  • daily_run_cap
    integer

Response


Example request

PATCH /api/projects/:project_id/llm_analytics/evaluation_reports/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/llm_analytics/evaluation_reports/:id/\
	-d evaluation="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "evaluation": "8b4883eb-9190-4e70-bfb9-71682af8a50b",
  "frequency": "scheduled",
  "rrule": "string",
  "starts_at": "2019-08-24T14:15:22Z",
  "timezone_name": "string",
  "next_delivery_date": "2019-08-24T14:15:22Z",
  "delivery_targets": null,
  "max_sample_size": -2147483648,
  "enabled": true,
  "deleted": true,
  "last_delivered_at": "2019-08-24T14:15:22Z",
  "report_prompt_guidance": "string",
  "trigger_threshold": 100,
  "cooldown_minutes": 60,
  "daily_run_cap": 1,
  "created_by": 0,
  "created_at": "2019-08-24T14:15:22Z"
}

Delete llm analytics evaluation reports

Evaluation report configs are deleted only when their evaluation is deleted. Use PATCH enabled=false to stop delivery.

Required API key scopes

llm_analytics:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/llm_analytics/evaluation_reports/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/llm_analytics/evaluation_reports/:id/

Example response

Status 405 No response body

Create llm analytics evaluation reports generate

Trigger immediate report generation.

Required API key scopes

llm_analytics:write

Path parameters

  • id
    string

Example request

POST /api/projects/:project_id/llm_analytics/evaluation_reports/: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/llm_analytics/evaluation_reports/:id/generate/

Example response

Status 202 No response body

List all llm analytics evaluation reports runs

List report runs (history) for this report.

Required API key scopes

llm_analytics:read

Path parameters

  • id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

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

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",
      "report": "838f2834-0545-48a4-b96c-dd2824df22eb",
      "content": {
        "evaluation_target": "generation",
        "title": "string",
        "sections": [
          {
            "title": "string",
            "content": "string"
          }
        ],
        "citations": [
          {
            "generation_id": "string",
            "trace_id": "string",
            "reason": "string"
          }
        ],
        "metrics": {
          "output_type": "boolean",
          "total_runs": 0,
          "result_counts": {
            "property1": 0,
            "property2": 0
          },
          "result_rates": {
            "property1": 0.1,
            "property2": 0.1
          },
          "period_start": "string",
          "period_end": "string",
          "previous_total_runs": 0,
          "previous_result_counts": {
            "property1": 0,
            "property2": 0
          },
          "previous_result_rates": {
            "property1": 0.1,
            "property2": 0.1
          },
          "pass_rate": 0.1,
          "previous_pass_rate": 0
        }
      },
      "metadata": {
        "output_type": "boolean",
        "total_runs": 0,
        "result_counts": {
          "property1": 0,
          "property2": 0
        },
        "result_rates": {
          "property1": 0.1,
          "property2": 0.1
        },
        "period_start": "string",
        "period_end": "string",
        "previous_total_runs": 0,
        "previous_result_counts": {
          "property1": 0,
          "property2": 0
        },
        "previous_result_rates": {
          "property1": 0.1,
          "property2": 0.1
        },
        "pass_rate": 0.1,
        "previous_pass_rate": 0
      },
      "period_start": "2019-08-24T14:15:22Z",
      "period_end": "2019-08-24T14:15:22Z",
      "delivery_status": "pending",
      "delivery_errors": [
        "string"
      ],
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}
Next page →

Community questions