Capturing large AI events

Contents

Public beta

Large event capture is in public beta. The capture v1 SDKs use it for every event sent with their AI capture method, and posthog-python and posthog-node also use it for their AI integrations: posthog-python 8.0.0+, posthog-node 6.0.0+, posthog-go v2.0.0+, the Rust SDK 1.0.0+, the iOS and Android SDKs 4.0.0+, and the Flutter SDK 6.0.0+ (except on the web). Older versions of posthog-python (7.39+) and posthog-node (5.49+, with @posthog/ai 8.8+) support it as an opt-in. We'd love to hear your feedback as we roll it out.

AI events can get big – a single generation can carry megabytes of prompt context or base64-encoded media, more than regular event capture accepts. To handle this, PostHog sends AI events like $ai_generation and $ai_embedding through a dedicated ingestion path that accepts events up to 8MB.

On the capture v1 SDKs, the SDK integrations always use this path. On older SDK versions, this path is opt-in, and how you opt in depends on how you capture AI events today.

Using the SDK integrations

By default, our SDK integrations redact base64 media and may truncate very long strings before capture. To capture everything in full, pass a single flag when creating your PostHog client:

from posthog import Posthog
posthog = Posthog(
"<ph_project_api_key>",
host="https://us.i.posthog.com",
enable_full_ai_capture=True
)

With the flag on, nothing is truncated or redacted. On posthog-python 8.0.0+ and posthog-node 6.0.0+, the integrations send AI events through the dedicated path with or without the flag, so the flag only turns off truncation and redaction. On older versions, the flag also opts in to the dedicated path. The one exception is privacy mode: when it's enabled, input and output content is still stripped, flag or no flag.

Calling capture_ai directly

If you build AI events yourself instead of using the integrations, call capture_ai (Python) or captureAi (Node) instead of capture. It takes the same arguments as capture and returns the captured event's UUID. The other capture v1 SDKs have an AI capture method too: EnqueueAI in Go, capture_ai in Rust, and captureAi on iOS, Android, and Flutter. See AI events for each SDK's method and settings. The mobile SDKs keep AI events in their own on-disk queue and drop an event over 8 MiB plus 64 KiB before sending it. On Flutter web, captureAi is a no-op.

Plain capture drops large events in Python

In posthog-python 7.x, capture() drops any event over 900 KiB before sending it and only logs an error. In 8.0, PostHog drops an event over the 1MB event limit and the SDK reports it as event_too_big. Either way, a large $ai_generation, for example one that carries base64 images or audio, never reaches PostHog. Use capture_ai() for these events.

from posthog import Posthog
posthog = Posthog("<ph_project_api_key>", host="https://us.i.posthog.com")
uuid = posthog.capture_ai(
"$ai_generation",
distinct_id="user_123",
properties={
"$ai_trace_id": trace_id,
"$ai_model": "gpt-5",
"$ai_input": messages,
"$ai_output_choices": choices,
},
)

Send content as your provider produced it, including base64 and data URIs – there's no need to reshape payloads. capture_ai captures exactly what you pass it, without truncating or redacting anything. Privacy mode doesn't apply here, so leave out any content you don't want stored.

In serverless and other short-lived environments, use the awaitable variant in Node so the event is delivered before the runtime exits:

TypeScript
await posthog.captureAiImmediate({ distinctId: 'user_123', event: '$ai_generation', properties })

In Python, call posthog.flush() before exit (or enable sync_mode), just like with capture.

Other platforms

Not on an SDK with an AI capture method? Build events with manual capture and point your capture requests at the dedicated AI endpoint instead of the regular one – same request format, different path:

Terminal
POST https://us.i.posthog.com/i/v0/ai/batch/

The dedicated endpoint only accepts events whose name starts with $ai_, and every event must include the $ai_model property. If a batch contains any other event, or an event without $ai_model, PostHog rejects the whole request with a 400 and records an ingestion warning. Send other events to the regular endpoint, which has no $ai_model requirement.

Capture v1 SDKs send AI events to /i/v1/ai/events instead. On that endpoint, PostHog checks each event on its own: it drops an event that isn't an AI event and ingests the rest of the batch. It doesn't require $ai_model. See capture v1.

Sending over OpenTelemetry

If you send AI traces with OpenTelemetry, your spans arrive over OTLP at a dedicated path:

Terminal
POST https://us.i.posthog.com/i/v0/ai/otel

Two size limits apply on this path, and they fail in different ways:

  • 4MB per export. PostHog rejects an OTLP export body over 4MB (measured after decompression for gzipped exports) with HTTP 413 and ingests none of its spans. Your collector logs the failure but does not retry it, per the OTLP spec, so the whole export is lost. This cap is lower than the per-event ceiling, so a batch of spans can exceed it before any single span does.
  • 8MB per event. Each span becomes one AI event, held to the same 8MB ceiling as the other paths. A span whose converted event exceeds the ceiling is dropped, but the rest of the export is ingested and the request still returns success. A failure response would only make your collector retry a span that can never fit. The only signal is a MessageSizeTooLarge ingestion warning: your application gets no error, and the span is lost silently.

To stay under the 4MB export cap, add the batch processor to your collector and lower both of its batch size settings, so it splits large batches into smaller exports:

YAML
processors:
batch:
send_batch_size: 100
send_batch_max_size: 100

Set both values: the collector refuses to start if send_batch_max_size is below send_batch_size, which defaults to 8192. Both settings count spans rather than bytes, so a batch of a few very large spans can pass the count and still exceed 4MB. Pick values that match your span sizes. Keep send_batch_max_size at or below 100: the endpoint also rejects any export containing more than 100 AI spans. For a single span that is too large on its own, capture it with capture_ai instead.

Limits

Events up to 8MB are accepted for now. The SDKs drop larger events before sending them, and log or report the drop instead. The limit will increase as the beta continues.

Over OpenTelemetry, a lower 4MB per-export cap also applies: an export over it is rejected with HTTP 413, while a span whose event exceeds 8MB is dropped without an application error.

Still have questions?

Was this page useful?