> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# AI Observability API

The API is both how trace data gets into PostHog and how you drive AI Observability from your own code. Your app sends LLM events through the [capture API](/docs/api/capture.md), and the [PostHog API](/docs/api.md) exposes the rest of the product – evaluations, datasets, review queues, clustering, summarization, and provider keys – so you can wire scoring and review into CI or your own tooling instead of clicking through the app.

## Before you start

1.  **Set up AI Observability** – [install a PostHog LLM SDK or provider integration](/docs/ai-observability/installation.md) so traces are captured.
2.  **Get API access** – [create a personal API key](/docs/api/personal-api-keys.md) with the scopes you need. See [authentication](#authentication) below.

## What you can do here

**Send traces in**

Everything AI Observability shows is built from events your app captures: `$ai_generation` for a single model call, `$ai_trace` for the request that wrapped it, `$ai_span` for the steps in between, `$ai_metric` for numbers you attach yourself, and `$ai_feedback` for what your users thought. The [PostHog SDKs](/docs/ai-observability/installation.md) send these for you when you wrap your model provider, and you can also [capture them manually](/docs/ai-observability/installation/manual-capture.md) if your setup isn't covered.

**Query your trace data**

The [query API](/docs/api/query.md) runs HogQL against your LLM events, so cost by model, latency percentiles, and error rates are all available without the dashboard. Prompts and completions live on the `posthog.ai_events` table rather than `events` – see the [data model](/docs/ai-observability/basics.md) for which fields go where.

**Run evaluations and reviews**

[Evaluations](/docs/ai-evals.md), their runs, and their scheduled reports are all API resources, alongside the [taggers](/docs/ai-evals/taggers.md) and score definitions that decide what gets scored. [Datasets](/docs/ai-evals/datasets.md) and dataset items, review queues, and individual trace reviews are too, so a human-review workflow can be built into your own tools.

**Manage enrichment**

[Clustering](/docs/ai-observability/clusters.md) runs and configuration, [trace summarization](/docs/ai-observability/summarization.md), and [custom parser](/docs/ai-observability/custom-parser.md) recipes are all callable, so the enrichment that normally happens in the app can be triggered from a pipeline.

**Configure model access**

Provider keys and their validation are managed through the API, as is the list of models available to your project. There's also a hosted LLM proxy that forwards completions to your configured provider, so the playground and evaluation runs have a model to call.

## Authentication

Use a [personal API key](/docs/api.md#authentication) passed as a bearer token, scoped to the least it needs.

Terminal

```bash
curl -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  https://us.posthog.com/api/projects/:project_id/evaluations/
```

Two things worth being careful about here. A personal API key belongs in a secret store, never in client-side code or a committed file. And provider keys – the credentials PostHog uses to call your model provider – are write-only through the API: you can set and validate one, but you can't read it back.

## Related

-   See the full [PostHog API reference](/docs/api.md).
-   Explore the same data in the [web app](/docs/ai-observability/surfaces/web-app.md).
-   Ask for it conversationally over [MCP](/docs/ai-observability/surfaces/mcp.md), which wraps much of this API in tools an agent can call.
-   Get your app sending traces with [installation](/docs/ai-observability/installation.md).

### Still have questions?

Ask PostHog AI

### Was this page useful?

HelpfulCould be better