
Send usage data from your Python code to PostHog.
Repo PostHog/posthog-python, read from GitHub 18 min ago. PostHog has not joined Take My Repo.
posthog.emails sends emails, uploads attachments and reads email statuses through /api/messaging/..., which takes the project from the project secret API key. It no longer calls /api/projects/@current/messaging/..., since PostHog is removing the @current alias. Needs PostHog Cloud, or a self-hosted PostHog from 2026-11-18 or later. Older self-hosted versions answer these calls with a 404. โ Thanks @rafaeelaudibert!posthog.exception_utils: only mark frames as in_app when their path is inside the project root directory, so sibling directories sharing the root's name as a prefix (e.g. /work/app-shared for root /work/app) are no longer treated as application code. โ Thanks @MaiAditya!PostHogSpanProcessor no longer breaks export of spans started inside a PostHog context on opentelemetry-sdk 1.20 and 1.21. The span copy that carries the context's distinct ID, session ID and tags held plain dicts and tuples, but those SDK versions' OTLP encoder reads .dropped from its attributes, events and links and failed with AttributeError. The copy now also keeps the counts of attributes, events and links the SDK dropped under its span limits, which it previously reported as 0. โ Thanks @fahad2932 for your first contribution ๐!posthog.ai.openai: report OpenAI cache-write tokens as $ai_cache_creation_input_tokens, for streaming and non-streaming calls. OpenAI reports them in input_tokens_details.cache_write_tokens (Responses) or prompt_tokens_details.cache_write_tokens (Chat Completions) and bills them above the input rate, but the wrapper read only cached_tokens, so cache writes were costed as plain input tokens. โ Thanks @alexeichhorn for your first contribution ๐!$session_id or $window_id that is not a string is not sent, because capture v1 would reject the whole batch, and the SDK logs a warning for each one. The warning names the key and the value's type, not the value. None counts as unset and drops without a warning. An empty string is sent. In posthog-python 7.x.x these values were sent as properties. โ Thanks @eli-r-ph!$trace_id and $span_id that the SDK takes from the active OpenTelemetry span now fill after the call's properties, context tags and super_properties, and before before_send. A $trace_id or $span_id in a context tag or super_properties now replaces the span's IDs, and setting either key stops the SDK adding both. AsyncPosthog follows the same rules. โ Thanks @eli-r-ph!capture_exception takes a level= argument on Client, AsyncPosthog and the module, which sets $exception_level (default "error"). Reserved exception properties passed in properties, such as $exception_list and $exception_level, are now ignored. In posthog-python 7.x.x they overrode the SDK's values with a DeprecationWarning. AsyncPosthog.capture_exception now sends $exception_level. โ Thanks @eli-r-ph!capture for a client object without capture_ai. Creating an OpenAI, Anthropic or Gemini wrapper, the LangChain CallbackHandler, or the OpenAI Agents or Claude Agent SDK processor with such a client now logs one error and captures no AI events. Provider calls still work. The error shows up when you set the integration up, and not after a provider call. A Client or AsyncPosthog instance, and the default global client, work as before. โ Thanks @eli-r-ph!$lib and $lib_version as they are at send time, whoever set them. If no $lib is set in the call's properties, a context tag or super_properties, the SDK sets both to posthog-python and the installed version. If $lib is posthog-python and $lib_version is missing, the SDK fills in the version. A $lib that names another library is sent with whatever $lib_version it has, so set both when you override them. Only a non-empty string counts as set. In posthog-python 7.x.x the SDK overwrote a $lib or $lib_version set in a call or a context tag. before_send can still change or remove both, and AsyncPosthog follows the same rules. โ Thanks @eli-r-ph!distinct_id after before_send, is dropped locally, an event that cannot be serialized is dropped alone (a non-finite float such as NaN is still sent as null), and a property key JSON cannot represent is dropped from its event. The analytics per-event limit is now capture's 10 MiB request limit instead of 900 KiB. A personal API key (phx_...) disables the client like an empty key. The SDK's own log lines no longer include event content or invalid timestamp values. AsyncPosthog follows the same rules. โ Thanks @eli-r-ph!disable_geoip argument to a call now counts as a value of that event. It wins over a $geoip_disable in context tags or super_properties, and a $geoip_disable in the call's own properties still wins over it. disable_geoip=False now sends $geoip_disable: false, so it turns GeoIP lookup on for that event even when a context tag or super_properties turns it off. The client's disable_geoip setting keeps its place below every caller value. AsyncPosthog follows the same rules. โ Thanks @eli-r-ph!group_identify falls back to the context distinct ID and then to $<group_type>_<group_key> instead of a random ID, and no longer adds the context session ID. alias() no longer takes its target from the context distinct ID. Context tags and options now apply to alias and group_identify, but context tags, context options, super_options and super_properties do not set process_person_profile on identify-style events ($identify, $create_alias, $merge_dangerously, $groupidentify, $set and $set_once) whose distinct ID the SDK did not generate. Those events default to True unless the call sets it. An empty or whitespace-only distinct_id counts as missing, and generated personless distinct IDs are UUIDv7. AsyncPosthog follows the same rules. โ Thanks @eli-r-ph!307 or 308 redirect only to the origin of host, at most 5 times, for the sync and async clients. Any other redirect fails the batch and reaches on_error. In posthog-python 7.x.x the sync client followed redirects to any origin and resent the event batch there. โ Thanks @eli-r-ph!path in posthog.request.post and after host in posthog.request.flags are keyword-only. With gzip removed, a posthog-python 7.x.x call that passed them by position bound them to the wrong parameter. It now raises TypeError. โ Thanks @eli-r-ph!uuid is still replaced with a generated one, but the SDK now logs one warning instead of an error, and the warning no longer includes the value. An empty string uuid counts as unset, so the SDK generates one without logging. AsyncPosthog follows the same rules. โ Thanks @eli-r-ph!posthog.mcp.instrument() and PostHogMCP changed $lib on every event the client sent, including the app's own, and the SDK name in its request headers, feature flag requests included. instrument() without a client relabeled the global client. Now only MCP analytics events report posthog-python-mcp, and everything else reports posthog-python. The label is set in each MCP event's own properties, so a $lib in super_properties no longer replaces it. before_send can. โ Thanks @eli-r-ph!PostHogMCP capture methods and McpAnalytics.capture take an event_options argument, and MCPAnalyticsOptions(event_options=...) sets options on every event instrument() captures automatically, from a function of (request, extra) like event_properties. An event without an identity still always sends process_person_profile: False. PostHogMCP.capture() keeps the core client's options argument. โ Thanks @eli-r-ph!AsyncPosthog.capture_exception now adds the active OpenTelemetry span's $trace_id and $span_id, like Client.capture_exception, even when capture_trace_context is off. โ Thanks @eli-r-ph!set_context_option before a task is published apply to every event captured while the task runs. propagate_context=False sends none of them. โ Thanks @eli-r-ph!posthog_properties also takes posthog_options (OpenAI, Anthropic, Gemini, sync and async, and the Claude Agent SDK query() and PostHogClaudeSDKClient), and the Gemini clients take it as a default for every call. LangChain's CallbackHandler and PostHogMiddleware, and instrument() and the tracing processors for OpenAI Agents and the Claude Agent SDK, take options=. LangChain also reads posthog_options from run metadata. These options win over context options and super_options. An event without a distinct ID still always sends process_person_profile: False, and a value that is not a dict is logged and ignored. โ Thanks @eli-r-ph!cacdb6f6 AI integrations (LLM wrappers, embeddings, LangChain and OpenAI Agents) treat an empty or whitespace-only distinct_id as missing, as the client does: the event uses its trace or run ID and is personless. Before, an empty ID gave streaming calls, embeddings and LangChain the trace or run ID with person processing on, so PostHog created a person for each trace or run. Non-streaming wrapper calls used a random personless ID, and OpenAI Agents already treated an empty ID as missing. A whitespace-only ID was sent as given. โ Thanks @eli-r-ph!
cacdb6f6 Capture timestamps always have six fractional-second digits, even on a whole second: 2026-01-02T03:04:05.000000+00:00, not 2026-01-02T03:04:05+00:00. This applies to the event timestamp, the batch created_at and the PostHog-Request-Timestamp header. The timestamp that before_send receives has the same format. โ Thanks @eli-r-ph!
cacdb6f6 Capture retry waits now vary randomly by up to 25%, so many clients do not retry at the same moment. โ Thanks @eli-r-ph!
cacdb6f6 Capture retries 404 and 429 responses like 408 and 500, 502, 503, 504, with the same backoff and Retry-After handling. โ Thanks @eli-r-ph!
cacdb6f6 Capture makes one connection try per attempt, so every physical request carries its own attempt number and request timestamp. posthog-python 7.x.x also retried a failed connection up to twice inside each attempt, reusing the request timestamp, which shifted the events' stored time by the time spent connecting.
When before_send raises, the error line names the event and the exception type, not the exception message. The traceback is logged at debug level.
Events without NaN or Infinity are encoded once, without first copying them to replace non-finite numbers. Events that contain them still send those values as null. โ Thanks @eli-r-ph!
cacdb6f6 Capture keeps the first event for each uuid in a request and drops the later copies. on_error now reports each dropped copy in CaptureError.drops as (uuid, "duplicate_event_uuid"), and the SDK does not resend it. Each entry of CaptureError.drops is a CaptureDroppedEvent from posthog.capture_send, a tuple that also has uuid and details fields. verdict_summary() counts each drop by its own reason. โ Thanks @eli-r-ph!