references/manual-capture.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Manual capture AI Observability installation
Canonical URL: https://posthog.com/docs/ai-observability/installation/manual-capture
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
Let AI instrument your LLM calls for you
Skip the manual setup — run this in your project and the wizard installs the SDK and wires up AI Observability for you.
npx @posthog/wizard ai-observability
PostHog Wizard hedgehog
Let AI instrument your LLM calls for you
-
1
Capture LLM events manually
If you use a different server-side SDK, or prefer to use the API, capture the data manually. Call the
capturemethod, or use the capture API.$ai_trace_idgroups the events of one LLM interaction into a trace.$ai_session_idis optional and groups related traces into a session, which is what the Sessions tab reads. Set it if your product has multi-turn conversations. Workloads that finish in a single trace, like batch jobs or one-shot generation, do not need it. Send it asnullon those to say so explicitly, which tells the instrumentation checklist the workload is complete rather than missing a session id.API
Capture via API
curl -X POST "https://us.i.posthog.com/i/v0/e/" \ -H "Content-Type: application/json" \ -d '{ "api_key": "<ph_project_token>", "event": "$ai_generation", "properties": { "distinct_id": "user_123", "$ai_trace_id": "trace_id_here", "$ai_session_id": "conversation-abc", "$ai_model": "gpt-5-mini", "$ai_provider": "openai", "$ai_input": [{"role": "user", "content": "Tell me a fun fact about hedgehogs"}], "$ai_input_tokens": 10, "$ai_output_choices": [{"role": "assistant", "content": "Hedgehogs have around 5,000 to 7,000 spines on their backs!"}], "$ai_output_tokens": 20, "$ai_latency": 1.5, "$ai_stream": true, "$ai_time_to_first_token": 0.25 } }'Node.js
1. Install
npm install posthog-node2. Initialize PostHog
import { PostHog } from 'posthog-node' const client = new PostHog('<ph_project_token>', { host: 'https://us.i.posthog.com' })3. Capture Event
// After your LLM call client.capture({ distinctId: 'user_123', event: '$ai_generation', properties: { $ai_trace_id: 'trace_id_here', $ai_session_id: 'conversation-abc', // optional: groups traces into one session $ai_model: 'gpt-5-mini', $ai_provider: 'openai', $ai_input: [{ role: 'user', content: 'Tell me a fun fact about hedgehogs' }], $ai_input_tokens: 10, $ai_output_choices: [{ role: 'assistant', content: 'Hedgehogs have around 5,000 to 7,000 spines on their backs!' }], $ai_output_tokens: 20, $ai_latency: 1.5, // For streaming responses, also include: // $ai_stream: true, // $ai_time_to_first_token: 0.25 } }) client.shutdown()Python
1. Install
pip install posthog2. Initialize PostHog
from posthog import Posthog posthog = Posthog("<ph_project_token>", host="https://us.i.posthog.com")3. Capture Event
# After your LLM call posthog.capture( distinct_id='user_123', event='$ai_generation', properties={ '$ai_trace_id': 'trace_id_here', '$ai_session_id': 'conversation-abc', # optional: groups traces into one session '$ai_model': 'gpt-5-mini', '$ai_provider': 'openai', '$ai_input': [{'role': 'user', 'content': 'Tell me a fun fact about hedgehogs'}], '$ai_input_tokens': 10, '$ai_output_choices': [{'role': 'assistant', 'content': 'Hedgehogs have around 5,000 to 7,000 spines on their backs!'}], '$ai_output_tokens': 20, '$ai_latency': 1.5, # For streaming responses, also include: # '$ai_stream': True, # '$ai_time_to_first_token': 0.25 } )Go
1. Install
go get github.com/posthog/posthog-go2. Initialize PostHog
import "github.com/posthog/posthog-go" client, _ := posthog.NewWithConfig("<ph_project_token>", posthog.Config{ Endpoint: "https://us.i.posthog.com", }) defer client.Close()3. Capture Event
// After your LLM call client.Enqueue(posthog.Capture{ DistinctId: "user_123", Event: "$ai_generation", Properties: map[string]interface{}{ "$ai_trace_id": "trace_id_here", // $ai_session_id is optional: it groups traces into one session "$ai_session_id": "conversation-abc", "$ai_model": "gpt-5-mini", "$ai_provider": "openai", "$ai_input_tokens": 10, "$ai_output_tokens": 20, "$ai_latency": 1.5, // For streaming responses, also include: // "$ai_stream": true, // "$ai_time_to_first_token": 0.25, }, })Ruby
1. Install
gem install posthog-ruby2. Initialize PostHog
require 'posthog' posthog = PostHog::Client.new({ api_key: '<ph_project_token>', host: 'https://us.i.posthog.com' })3. Capture Event
# After your LLM call posthog.capture({ distinct_id: 'user_123', event: '$ai_generation', properties: { '$ai_trace_id' => 'trace_id_here', '$ai_session_id' => 'conversation-abc', # optional: groups traces into one session '$ai_model' => 'gpt-5-mini', '$ai_provider' => 'openai', '$ai_input_tokens' => 10, '$ai_output_tokens' => 20, '$ai_latency' => 1.5 # For streaming responses, also include: # '$ai_stream' => true, # '$ai_time_to_first_token' => 0.25 } })PHP
1. Install
composer require posthog/posthog-php2. Initialize PostHog
<?php require_once __DIR__ . '/vendor/autoload.php'; use PostHog\PostHog; PostHog::init('<ph_project_token>', [ 'host' => 'https://us.i.posthog.com' ]);3. Capture Event
// After your LLM call PostHog::capture([ 'distinctId' => 'user_123', 'event' => '$ai_generation', 'properties' => [ '$ai_trace_id' => 'trace_id_here', '$ai_session_id' => 'conversation-abc', // optional: groups traces into one session '$ai_model' => 'gpt-5-mini', '$ai_provider' => 'openai', '$ai_input_tokens' => 10, '$ai_output_tokens' => 20, '$ai_latency' => 1.5 // For streaming responses, also include: // '$ai_stream' => true, // '$ai_time_to_first_token' => 0.25 ] ]); -
2
Event properties
Each event type has specific properties. See the tabs below for detailed property documentation for each event type.
Generation
A generation is a single call to an LLM.
Event name:
$ai_generationCore properties
| Property | Description | | --- | --- | |
$ai_trace_id| The trace ID (a UUID to group AI events) likeconversation_idMust contain only letters, numbers, and special characters:-,_,~,.,@,(,),!,',:,\|Example:d9222e05-8708-41b8-98ea-d4a21849e761| |$ai_session_id| (Optional) Groups related traces into a session, which is what the Sessions tab reads. Set it if your product has multi-turn conversations. A workload that finishes in a single trace does not need it. Send it as null to say so explicitly, which tells the instrumentation checklist the workload is complete rather than missing a session id. Example:session-abc-123,conv-user-456| |$ai_span_id| (Optional) Unique identifier for this generation | |$ai_span_name| (Optional) Name given to this generation Example:summarize_text| |$ai_parent_id| (Optional) Parent span ID for tree view grouping | |$ai_model| The model used Example:gpt-5-mini| |$ai_provider| The LLM provider Example:openai,anthropic,gemini| |$ai_input| List of messages sent to the LLM. Each message should have aroleproperty with one of:"user","system", or"assistant"Example:json [ { "role": "user", "content": [ { "type": "text", "text": "What's in this image?" }, { "type": "image", "image": "https://example.com/image.jpg" }, { "type": "function", "function": { "name": "get_weather", "arguments": { "location": "San Francisco" } } } ] } ]| |$ai_input_tokens| The number of tokens in the input (often found in response.usage) | |$ai_output_choices| List of response choices from the LLM. Each choice should have aroleproperty with one of:"user","system", or"assistant"Example:json [ { "role": "assistant", "content": [ { "type": "text", "text": "I can see a hedgehog in the image." }, { "type": "function", "function": { "name": "get_weather", "arguments": { "location": "San Francisco" } } } ] } ]| |$ai_output_tokens| The number of tokens in the output (often found in response.usage) | |$ai_latency| (Optional) The latency of the LLM call in seconds | |$ai_time_to_first_token| (Optional) Time to first token in seconds. Only applicable for streaming responses. | |$ai_http_status| (Optional) The HTTP status code of the response | |$ai_base_url| (Optional) The base URL of the LLM provider Example:https://api.openai.com/v1| |$ai_request_url| (Optional) The full URL of the request made to the LLM API Example:https://api.openai.com/v1/chat/completions| |$ai_is_error| (Optional) Boolean to indicate if the request was an error | |$ai_error| (Optional) The error message or object | |$ai_stop_reason| (Optional) The reason the model stopped generating tokens Example:end_turn,stop,max_tokens,tool_use|Cost properties
Cost properties are optional as we can automatically calculate them from model and token counts. If you want, you can provide your own cost properties or custom pricing instead.
Pre-calculated costs
| Property | Description | | --- | --- | |
$ai_input_cost_usd| (Optional) The cost in USD of the input tokens | |$ai_output_cost_usd| (Optional) The cost in USD of the output tokens | |$ai_request_cost_usd| (Optional) The cost in USD for the requests | |$ai_web_search_cost_usd| (Optional) The cost in USD for the web searches | |$ai_total_cost_usd| (Optional) The total cost in USD (sum of all cost components) | |$ai_cost_passthrough| (Optional) Set this when your provider reports the real cost, such as an LLM gateway. We keep your$ai_total_cost_usdand leave the input and output costs unset. |Custom pricing
| Property | Description | | --- | --- | |
$ai_input_token_price| (Optional) Price per input token (used to calculate$ai_input_cost_usd) | |$ai_output_token_price| (Optional) Price per output token (used to calculate$ai_output_cost_usd) | |$ai_cache_read_token_price| (Optional) Price per cached token read | |$ai_cache_write_token_price| (Optional) Price per cached token write. For custom Anthropic pricing, this applies to both cache TTLs unless$ai_cache_write_1h_token_priceis set. | |$ai_cache_write_1h_token_price| (Optional) Price per token written to Anthropic's 1-hour cache. Takes precedence over$ai_cache_write_token_pricefor 1-hour writes. | |$ai_request_price| (Optional) Price per request | |$ai_request_count| (Optional) Number of requests (defaults to 1 if$ai_request_priceis set) | |$ai_web_search_price| (Optional) Price per web search | |$ai_web_search_count| (Optional) Number of web searches performed |Cache properties
| Property | Description | | --- | --- | |
$ai_cache_read_input_tokens| (Optional) Number of tokens read from cache | |$ai_cache_creation_input_tokens| (Optional) Number of tokens written to cache For Anthropic events, PostHog uses the TTL-specific counts instead of this aggregate when both are present. The aggregate should equal their sum. If either count is missing, PostHog uses the aggregate. Built-in Gemini pricing uses normal input rates for cache writes and does not estimate cache storage fees. Custom pricing can override these rates. | |$ai_cache_creation_5m_input_tokens| (Optional) Number of tokens written to Anthropic's 5-minute cache | |$ai_cache_creation_1h_input_tokens| (Optional) Number of tokens written to Anthropic's 1-hour cache | |$ai_cache_reporting_exclusive| (Optional) Whether cache tokens are excluded from$ai_input_tokens. Whentrue, cache tokens are separate from input tokens. Whenfalse, input tokens already include cache tokens. Defaults totruefor Anthropic provider or Claude models,falseotherwise. |Model parameters
| Property | Description | | --- | --- | |
$ai_temperature| (Optional) Temperature parameter used in the LLM request | |$ai_stream| (Optional) Whether the response was streamed | |$ai_max_tokens| (Optional) Maximum tokens setting for the LLM response | |$ai_tools| (Optional) Tools/functions available to the LLM Example:json [ { "type": "function", "function": { "name": "get_weather", "parameters": {} } } ]|Trace
A trace is a group that contains multiple spans, generations, and embeddings. Traces can be manually sent as events or appear as pseudo-events automatically created from child events.
Event name:
$ai_traceCore properties
| Property | Description | | --- | --- | |
$ai_trace_id| The trace ID (a UUID to group related AI events together) Must contain only letters, numbers, and special characters:-,_,~,.,@,(,),!,',:,\|Example:d9222e05-8708-41b8-98ea-d4a21849e761| |$ai_session_id| (Optional) Groups related traces into a session, which is what the Sessions tab reads. Set it if your product has multi-turn conversations. A workload that finishes in a single trace does not need it. Send it as null to say so explicitly, which tells the instrumentation checklist the workload is complete rather than missing a session id. Must contain only letters, numbers, and special characters:-,_,~,.,@,(,),!,',:,\|Example:session-abc-123,conv-user-456| |$ai_input_state| The input of the whole trace Example:json [ { "role": "user", "content": "What's the weather in SF?" } ]or any JSON-serializable state | |$ai_output_state| The output of the whole trace Example:json [ { "role": "assistant", "content": "The weather in San Francisco is..." } ]or any JSON-serializable state | |$ai_latency| (Optional) The latency of the trace in seconds | |$ai_span_name| (Optional) The name of the trace Example:chat_completion,rag_pipeline| |$ai_is_error| (Optional) Boolean to indicate if the trace encountered an error | |$ai_error| (Optional) The error message or object if the trace failed |Pseudo-trace Events
When you send generation (
$ai_generation), span ($ai_span), or embedding ($ai_embedding) events with a$ai_trace_id, PostHog automatically creates a pseudo-trace event that appears in the dashboard as a parent grouping. These pseudo-traces:- Are not actual events in your data
- Automatically aggregate metrics from child events (latency, tokens, costs)
- Provide a hierarchical view of your AI operations
- Do not require sending an explicit
$ai_traceevent
This means you can either:
- Send explicit
$ai_traceevents to control the trace metadata - Let PostHog automatically create pseudo-traces from your generation/span events
Span
A span is a single action within your application, such as a function call or vector database search.
Event name:
$ai_spanCore properties
| Property | Description | | --- | --- | |
$ai_trace_id| The trace ID (a UUID to group related AI events together) Must contain only letters, numbers, and the following characters:-,_,~,.,@,(,),!,',:,\|Example:d9222e05-8708-41b8-98ea-d4a21849e761| |$ai_session_id| (Optional) Groups related traces into a session, which is what the Sessions tab reads. Set it if your product has multi-turn conversations. A workload that finishes in a single trace does not need it. Send it as null to say so explicitly, which tells the instrumentation checklist the workload is complete rather than missing a session id. Example:session-abc-123,conv-user-456| |$ai_span_id| (Optional) Unique identifier for this span Example:bdf42359-9364-4db7-8958-c001f28c9255| |$ai_span_name| (Optional) The name of the span Example:vector_search,data_retrieval,tool_call| |$ai_parent_id| (Optional) Parent ID for tree view grouping (trace_idor anotherspan_id) Example:537b7988-0186-494f-a313-77a5a8f7db26| |$ai_input_state| The input state of the span Example:json { "query": "search for documents about hedgehogs" }or any JSON-serializable state | |$ai_output_state| The output state of the span Example:json { "results": ["doc1", "doc2"], "count": 2 }or any JSON-serializable state | |$ai_latency| (Optional) The latency of the span in seconds Example:0.361| |$ai_is_error| (Optional) Boolean to indicate if the span encountered an error | |$ai_error| (Optional) The error message or object if the span failed Example:json { "message": "Connection timeout", "code": "TIMEOUT" }|Embedding
An embedding is a single call to an embedding model to convert text into a vector representation.
Event name:
$ai_embeddingCore properties
| Property | Description | | --- | --- | |
$ai_trace_id| The trace ID (a UUID to group related AI events together). Must contain only letters, numbers, and special characters:-,_,~,.,@,(,),!,',:,\|Example:d9222e05-8708-41b8-98ea-d4a21849e761| |$ai_session_id| (Optional) Groups related traces into a session, which is what the Sessions tab reads. Set it if your product has multi-turn conversations. A workload that finishes in a single trace does not need it. Send it as null to say so explicitly, which tells the instrumentation checklist the workload is complete rather than missing a session id. Example:session-abc-123,conv-user-456| |$ai_span_id| (Optional) Unique identifier for this embedding operation | |$ai_span_name| (Optional) Name given to this embedding operation Example:embed_user_query,index_document| |$ai_parent_id| (Optional) Parent span ID for tree-view grouping | |$ai_model| The embedding model used Example:text-embedding-3-small,text-embedding-ada-002| |$ai_provider| The LLM provider Example:openai,cohere,voyage| |$ai_input| The text to embed Example:"Tell me a fun fact about hedgehogs"or array of strings for batch embeddings | |$ai_input_tokens| The number of tokens in the input | |$ai_latency| (Optional) The latency of the embedding call in seconds | |$ai_http_status| (Optional) The HTTP status code of the response | |$ai_base_url| (Optional) The base URL of the LLM provider Example:https://api.openai.com/v1| |$ai_request_url| (Optional) The full URL of the request made to the embedding API Example:https://api.openai.com/v1/embeddings| |$ai_is_error| (Optional) Boolean to indicate if the request was an error | |$ai_error| (Optional) The error message or object if the embedding failed |Cost properties
Cost properties are optional as we can automatically calculate them from model and token counts. If you want, you can provide your own cost property instead.
| Property | Description | | --- | --- | |
$ai_input_cost_usd| (Optional) Cost in USD for input tokens | |$ai_output_cost_usd| (Optional) Cost in USD for output tokens (usually 0 for embeddings) | |$ai_total_cost_usd| (Optional) Total cost in USD | -
Verify traces and generations
Recommended
Confirm LLM events are being sent to PostHog
Let's make sure LLM events are being captured and sent to PostHog. Under AI Observability, you should see rows of data appear in the Traces and Generations tabs.
LLM generations in PostHog
-
3
Next steps
Recommended
Now that you're capturing AI conversations, continue with the resources below to learn what else AI Observability enables within the PostHog platform.
| Resource | Description | | --- | --- | | Basics | Learn the basics of how LLM calls become events in PostHog. | | Generations | Read about the
$ai_generationevent and its properties. | | Traces | Explore the trace hierarchy and how to use it to debug LLM calls. | | Spans | Review spans and their role in representing individual operations. | | Anaylze LLM performance | Learn how to create dashboards to analyze LLM performance. |
Large events
For large events, use the dedicated AI ingestion path – see [capturing large AI events](https://posthog.com/docs/ai-observabilit