Upgrading to capture v1 SDKs
Contents
PostHog SDKs are moving to capture v1, a new way to send events. Each SDK moves to v1 in a new major version. Capture v1 gives you:
- A result for every event. One bad event no longer fails the whole batch, and your SDK tells you which events PostHog didn't store and why.
- Event options. Settings like person processing move out of
$-prefixed properties into a separateoptionsobject. - Safer retries. SDKs retry only what can succeed and resend only the events that need it.
- More compression choices.
gzip,deflate,br, andzstd. - A separate path for AI events. Large AI events have their own queue and limits.
The iOS, Android, and Flutter SDKs have no error handler and compress with gzip or not at all. They log the events PostHog didn't store only when debug logging is on.
The legacy capture endpoints still work, and SDK versions that use them stay supported. We plan to retire the legacy endpoints in the future and will announce a date well in advance.
SDKs and versions
Each SDK below moves to capture v1 in a new major version. These versions include breaking changes. Read your SDK's migration guide before you upgrade.
| SDK | First version with capture v1 | Platforms on v1 | Migration guide |
|---|---|---|---|
| Python | 8.0.0 | All | 7.x to 8.0 |
| Go | v2.0.0 (module github.com/posthog/posthog-go/v2; the otel and posthogmcpsdk modules move to /v2 too) | All | v1 to v2 |
| Rust | 1.0.0 | All | 0.x to 1.0 |
| Node.js | 6.0.0 | Server (posthog-node) | 5.x to 6.0 |
| iOS | 4.0.0 | iOS, macOS, tvOS, watchOS, and visionOS | 3.x to 4.0 |
| Android | 4.0.0 | Android | 3.x to 4.0 |
| Flutter | 6.0.0 | iOS, macOS, Android, Windows, and Linux | 5.x to 6.0 |
Other SDKs, including the JavaScript Web SDK and React Native, use legacy capture. Flutter apps on the web use the JavaScript Web SDK, so they use legacy capture too.
What changes for everyone
These changes apply to every SDK on capture v1. Your SDK's migration guide covers changes that only apply to it.
Every event needs its own UUID
SDKs generate a UUIDv7 for each event. If you set an event's UUID yourself, use a new one for every event. Don't reuse an order ID, request ID, or message ID across events. If one request repeats a UUID, PostHog keeps the first event with it and drops the rest, and your SDK reports the dropped copies.
Event options replace legacy option properties
Legacy option properties are the $-prefixed properties legacy capture reads as settings. Set these settings in an event's options instead:
| Option | Replaces |
|---|---|
process_person_profile | $process_person_profile |
cookieless_mode | $cookieless_mode |
disable_skew_correction | $ignore_sent_at |
product_tour_id | $product_tour_id |
On iOS, Android, and Flutter, capture, screen, identify, and the other event methods take options too. The iOS, Android, and Flutter migration guides list every method that takes it.
Legacy option properties still work, but an option overrides its legacy property. Use options.
SDKs send options exactly as you set them. PostHog ignores option names it doesn't know, and drops an event whose option value it can't read, with the detail invalid_options. See event options for the types each option takes.
How values combine
You can set properties and options in several places. When the same key is set in more than one place, the most specific value wins:
- The capture call – the properties and options you pass for this event
- Context – values set for the current request or job, such as Python's
new_context()andtag(), Go'sRequestContext, or thepropertiesandoptionsyou pass to Node.js'swithContext() - Global defaults – values set on the client for every event, such as Python's
super_propertiesandsuper_options, Go'sDefaultEventPropertiesandDefaultEventOptions, Node.js'sregister()andregisterOptions(), or super properties set withregister()on iOS and Android - SDK values – properties the SDK adds itself, such as
$is_server, and the$feature/<key>and$active_feature_flagsproperties from the feature flags you attach to an event. Some SDKs also add the$trace_idand$span_idof the active OpenTelemetry span to some events. Your SDK's migration guide says when
The SDK's own $lib and $lib_version come after all of these. They fill in only when the event doesn't set $lib, or sets the SDK's own name without a version. See library name and version.
Then before_send runs. It sees the combined event, including options, and can change or remove anything.
Check your before_send hooks when you upgrade. The SDK sends the event your hook returns, as it is. If your hook builds a new event instead of changing the one it got, copy options too, or the event goes out without them. That includes process_person_profile: false, which server SDKs set for an event with no distinct ID, so PostHog would create a person for its generated ID. The Android SDK is the exception: a new event without options keeps the options of the event your hook got, so return an empty options map to clear them. To change a setting in the hook, edit options.
A few details:
- A value from a lower layer only fills keys you didn't set higher up. This is a change: before v1, some SDKs let global values overwrite the ones you passed on the call.
- A property set to
null(orNone, ornil) counts as set, so a lower layer can't replace it. An option set tonullcounts as unset. - On Python, Go, Node.js, and Rust,
$set,$set_once,$groups, and$group_setmerge key by key, and the most specific value wins for each key. On iOS, Android, and Flutter, a$setor$set_onceyou pass on the call replaces a registered one, as before. - A
$setin a global or context layer adds those person properties to every event that layer reaches. - On server SDKs,
process_person_profile: falsein a global or context layer also reaches identify, alias, and group identify events. PostHog drops those events when person processing is off, and your error handler doesn't report it, because PostHog accepts them first. Set person processing on each capture call instead of in a layer that covers these calls. - Not every SDK has every layer. Rust has no global layer, and iOS, Android, and Flutter have global properties but no global options or context layer. Your SDK's migration guide lists the layers it has and which calls they reach.
Person processing
- On server SDKs, adding groups to an event doesn't turn on person processing. The Rust SDK did before 1.0. To use group analytics, send events with person processing on.
- On iOS, Android, and Flutter, an event with groups still turns on person processing, as before, unless
personProfilesis set tonever. - On server SDKs, an event without a distinct ID becomes an anonymous event with a generated ID, and doesn't create a person profile. Only the
process_person_profileoption can change that. If the event belongs to a person, pass their distinct ID. (The Go SDK returns an error instead when the call has no request context.) - Use a real distinct ID: one visitor, or your own ID for a known user. See choosing a distinct ID.
- On server SDKs, group identify without a distinct ID uses
$<group type>_<group key>as the event's distinct ID. If that is over 200 bytes, pass adistinct_idexplicitly, or PostHog drops the event.
Limits
PostHog checks every event and drops only the events that break a rule. On server SDKs, your error handler reports each drop with its reason. Limits count UTF-8 bytes, not characters.
- Event names: up to 200 bytes. This is new: legacy capture had no limit. Longer names are dropped (
event_name_too_long). - Distinct IDs: up to 200 bytes. Legacy capture shortened longer IDs and kept the event. Capture v1 drops the event (
distinct_id_too_large). - Distinct IDs are strings. SDKs send them as strings for you. If a
before_sendhook changesdistinct_id, keep it a string: PostHog rejects a whole request that contains a non-string ID, so the SDK drops that event before sending. See field types. - Properties are an object, and option values are readable. Otherwise PostHog drops the event (
malformed_event_properties,invalid_options). - Event UUIDs are unique. See every event needs its own UUID.
See limits and validation for every rule.
Other changes
- Library name and version. A
$liband$lib_versionyou set in an event's properties, or in abefore_sendhook, are stored as you set them. Integrations such as MCP analytics use this to label their own events. When an event doesn't set$lib, the SDK fills in both with its own name and version. Set both when you override them: an event whose$libnames another library doesn't get the SDK's version. See library name and version. - Session IDs.
$session_idand$window_idmust be strings. Other values are dropped from the event, with a warning in your logs. The iOS, Android, and Flutter SDKs log it only when debug logging is on. - Timestamps. SDKs send every timestamp with at least millisecond precision, writing all three digits even when they're zero (
.000), and keep any finer precision you provide. The iOS and Android SDKs, and Flutter on those platforms, send milliseconds only. SDKs no longer reject future timestamps – PostHog handles those. - API keys. An empty project token, or a personal API key (
phx_…) used as one, turns the client off and logs one error, instead of failing your app. - Redirects. SDKs follow a redirect only to the same scheme, host, and port, and only a
307or308. Any other redirect is an error. If you send events through a proxy that redirects, point the SDK at the final address. - Logs. Debug logs no longer include event contents, and some log messages changed. Update any alerts that match on old log text.
Configuration
Some defaults changed in the new major versions. These are the capture settings that matter most for v1:
| Setting | Default | Python | Go | Rust | Node.js |
|---|---|---|---|---|---|
| Retries | 3 retries (4 attempts) | max_retries | MaxRetries | max_capture_attempts (counts the first attempt) | captureMaxRetries |
| Retry wait | 100ms, doubling, up to 30s, with jitter | – | MaxRetryBackoff | retry_initial_backoff_ms, retry_max_backoff_ms | – |
| Events per request | 100 | flush_at | BatchSize | max_batch_size | maxBatchSize |
| Queued events that start a send | 100 (Node.js: 20) | flush_at | BatchSize | flush_at | flushAt |
| Flush interval | 5 seconds | flush_interval | Interval | flush_interval_ms | flushInterval |
| Compression | None (Node.js: gzip) | capture_compression | Compression | capture_compression | captureCompression |
| Compression formats | – | gzip, deflate, zstd (needs posthog[zstd]) | gzip, deflate, br, zstd | gzip, deflate, br, zstd | gzip, deflate, zstd |
| Skip GeoIP lookup | On for Python, Go, and Node.js, off for Rust | disable_geoip | DisableGeoIP | disable_geoip | disableGeoip |
| Error handler | – | on_error | Callback | on_error | on('error', …) |
| Modify or drop events | – | before_send | BeforeSend | before_send | before_send |
| Historical migration | Off | historical_migration | HistoricalMigration | capture_batch(events, true) | historicalMigration |
Historical migration marks every event in a request, so SDKs never send historical and live events together. In Python, Go, and Node.js, a client with it on sends only historical events, so use a separate client for live events. In Rust, it applies to that capture_batch call only.
SDKs split large batches into requests of 5MB or less (Go: about 500KB by default), and send any single event that's bigger than that in its own request. Your SDK's migration guide lists every new and changed setting. Mobile SDKs keep a persistent queue and retry differently; the iOS, Android, and Flutter migration guides list their settings.
Retries and failures
SDKs on capture v1 retry a request that fails with 404, 408, 429, 500, 502, 503, 504, or a network error, and they resend only the events PostHog asked them to retry. Every other response is final. Each wait doubles, with some randomness added so many clients don't retry at the same moment.
Let the SDK handle retries. Don't wrap its capture calls in your own retry loop – that can send events twice and slow your app down.
On server SDKs, add an error handler to see what PostHog didn't store. It reports the events PostHog dropped, with the reason from the result details. Without a handler, the SDK logs one line per failed batch.
If your project hits a billing limit, PostHog stops storing events and answers with 402 when nothing in a request can be stored. The SDK reports this as a failure on each send until the limit resets or you raise it. If only some events in a request are over a product's quota, PostHog answers with 200 and drops only those events, with the quota named in their result details.
AI events
Send AI events (any event whose name starts with $ai_) with your SDK's AI capture method. It has its own queue, compression setting, and size limit, separate from your other events. PostHog owns the $ai_ prefix, so don't use it for your own events.
| SDK | AI capture method | AI settings |
|---|---|---|
| Python | capture_ai | capture_ai_compression, capture_ai_max_queue_size, capture_ai_timeout, capture_ai_max_event_bytes |
| Go | EnqueueAI | CaptureAICompression, CaptureAIMaxQueueSize, CaptureAIBatchUploadTimeout |
| Rust | capture_ai | capture_ai_compression, capture_ai_max_queue_size |
| Node.js | captureAi | captureAiCompression, captureAiMaxQueueSize, captureAiRequestTimeoutMs |
| iOS, Android, and Flutter | captureAi | captureAiCompression, captureAiMaxQueueSize, captureAiTimeout, captureAiMaxEventBytes |
On iOS, Android, and Flutter, captureAi takes the same arguments as capture. The iOS, Android, and Flutter migration guides cover their AI queue settings.
capture doesn't move $ai_ events to the AI path for you. For now, PostHog still accepts AI events sent with capture, so existing code keeps working while you upgrade. This is temporary, and large AI events always need the AI method. Calling flush or shutdown sends both queues. See capturing large AI events for limits and the AI integrations.
The Python and Node.js AI integrations take event options per call: posthog_options in Python and posthogOptions in Node.js.
Proxies
If you send events through a reverse proxy, make sure it:
- Forwards
/i/v1/analytics/eventsand/i/v1/ai/events - Passes the
Authorizationheader and everyPostHog-*header through unchanged, along withContent-Type,Content-Encoding, andUser-Agent - Returns PostHog's status code and response body unchanged, so your SDK sees the result for each event
- Accepts request bodies of at least 20MB, the most PostHog accepts on the AI endpoint. AI requests can be larger than 1MB, the default limit in nginx and ingress-nginx, and a
413from your proxy drops the events in that request (the iOS, Android, and Flutter SDKs split the batch first, and drop only an event that's too large on its own)
Capture v1 SDKs send your project token in the Authorization header, as Bearer <token>. Without it, PostHog returns 401 and the SDK drops the events. If your proxy removes other credentials, keep Authorization values that start with Bearer phc_, Bearer phs_, or Bearer phx_ (server SDKs send the last two for features such as local feature flag evaluation and remote config), plus the exact Bearer <key> value of any older key without one of these prefixes. Some older versions of our proxy guides removed this header and kept the 1MB default request limit, so check your proxy against the current proxy guides and the proxy reference. The managed reverse proxy already serves both capture v1 endpoints and passes these headers through.
Learn more
- Capture API (v1) – headers, request and response formats, and every result detail
- The SDK specs for capture and AI capture – how every SDK behaves on capture v1
- Your SDK's migration guide, linked in the table above





