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 separate options object.
  • Safer retries. SDKs retry only what can succeed and resend only the events that need it.
  • More compression choices. gzip, deflate, br, and zstd.
  • 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

Major versions with breaking changes

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.

SDKFirst version with capture v1Platforms on v1Migration guide
Python8.0.0All7.x to 8.0
Gov2.0.0 (module github.com/posthog/posthog-go/v2; the otel and posthogmcpsdk modules move to /v2 too)Allv1 to v2
Rust1.0.0All0.x to 1.0
Node.js6.0.0Server (posthog-node)5.x to 6.0
iOS4.0.0iOS, macOS, tvOS, watchOS, and visionOS3.x to 4.0
Android4.0.0Android3.x to 4.0
Flutter6.0.0iOS, macOS, Android, Windows, and Linux5.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:

OptionReplaces
process_person_profile$process_person_profile
cookieless_mode$cookieless_mode
disable_skew_correction$ignore_sent_at
product_tour_id$product_tour_id

posthog.capture(
"signed_up",
distinct_id="user_123",
properties={"plan": "pro"},
options={"process_person_profile": True},
)

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:

  1. The capture call – the properties and options you pass for this event
  2. Context – values set for the current request or job, such as Python's new_context() and tag(), Go's RequestContext, or the properties and options you pass to Node.js's withContext()
  3. Global defaults – values set on the client for every event, such as Python's super_properties and super_options, Go's DefaultEventProperties and DefaultEventOptions, Node.js's register() and registerOptions(), or super properties set with register() on iOS and Android
  4. SDK values – properties the SDK adds itself, such as $is_server, and the $feature/<key> and $active_feature_flags properties from the feature flags you attach to an event. Some SDKs also add the $trace_id and $span_id of 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 (or None, or nil) counts as set, so a lower layer can't replace it. An option set to null counts as unset.
  • On Python, Go, Node.js, and Rust, $set, $set_once, $groups, and $group_set merge key by key, and the most specific value wins for each key. On iOS, Android, and Flutter, a $set or $set_once you pass on the call replaces a registered one, as before.
  • A $set in a global or context layer adds those person properties to every event that layer reaches.
  • On server SDKs, process_person_profile: false in 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 personProfiles is set to never.
  • 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_profile option 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 a distinct_id explicitly, 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_send hook changes distinct_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 $lib and $lib_version you set in an event's properties, or in a before_send hook, 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 $lib names another library doesn't get the SDK's version. See library name and version.
  • Session IDs. $session_id and $window_id must 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 307 or 308. 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:

SettingDefaultPythonGoRustNode.js
Retries3 retries (4 attempts)max_retriesMaxRetriesmax_capture_attempts (counts the first attempt)captureMaxRetries
Retry wait100ms, doubling, up to 30s, with jitter–MaxRetryBackoffretry_initial_backoff_ms, retry_max_backoff_ms–
Events per request100flush_atBatchSizemax_batch_sizemaxBatchSize
Queued events that start a send100 (Node.js: 20)flush_atBatchSizeflush_atflushAt
Flush interval5 secondsflush_intervalIntervalflush_interval_msflushInterval
CompressionNone (Node.js: gzip)capture_compressionCompressioncapture_compressioncaptureCompression
Compression formats–gzip, deflate, zstd (needs posthog[zstd])gzip, deflate, br, zstdgzip, deflate, br, zstdgzip, deflate, zstd
Skip GeoIP lookupOn for Python, Go, and Node.js, off for Rustdisable_geoipDisableGeoIPdisable_geoipdisableGeoip
Error handler–on_errorCallbackon_erroron('error', …)
Modify or drop events–before_sendBeforeSendbefore_sendbefore_send
Historical migrationOffhistorical_migrationHistoricalMigrationcapture_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.

from posthog import Posthog
def on_error(error, batch):
# error is a CaptureError: status, drops, event_results, verdict_summary()
print("PostHog capture failed:", error.verdict_summary())
posthog = Posthog("<ph_project_token>", host="https://us.i.posthog.com", on_error=on_error)

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.

SDKAI capture methodAI settings
Pythoncapture_aicapture_ai_compression, capture_ai_max_queue_size, capture_ai_timeout, capture_ai_max_event_bytes
GoEnqueueAICaptureAICompression, CaptureAIMaxQueueSize, CaptureAIBatchUploadTimeout
Rustcapture_aicapture_ai_compression, capture_ai_max_queue_size
Node.jscaptureAicaptureAiCompression, captureAiMaxQueueSize, captureAiRequestTimeoutMs
iOS, Android, and FluttercaptureAicaptureAiCompression, captureAiMaxQueueSize, captureAiTimeout, captureAiMaxEventBytes

posthog.capture_ai(
"$ai_generation",
distinct_id="user_123",
properties={"$ai_model": "gpt-5", "$ai_input_tokens": 120},
)

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/events and /i/v1/ai/events
  • Passes the Authorization header and every PostHog-* header through unchanged, along with Content-Type, Content-Encoding, and User-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 413 from 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

Still have questions?

Was this page useful?