Subchapter 82.49

PostHog Python

references/posthog-python.mdMarkdown64 KBView on GitHub

AI agents: this is one page from PostHog’s docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt (opens in a new tab)

PostHog Python SDK

PostHog Python · Instrument Product Analytics · PostHog/skills · Skills Docs

project_api_key? (str) - PostHog project API key/token.
host (any) - PostHog host. Defaults to the US ingestion endpoint when not set. App hosts such as https://us.posthog.com are mapped to the corresponding ingestion host.
debug (bool) - Enable verbose SDK logging and re-raise errors from public API methods.
max_queue_size (int) - Maximum number of events buffered before upload.
send (bool) - If False, queueing succeeds but events are not sent.
on_error (any) - Optional callback invoked by background consumers when an upload fails. Keep it short and non-blocking. Calling lifecycle methods directly is safe and deferred, but do not start another thread or task that calls flush(), join(), or shutdown() and then wait for it from the callback.
flush_at (int) - Number of queued events that triggers a batch upload.
flush_interval (float) - Maximum seconds a background consumer waits before flushing a partial batch.
gzip (bool) - Whether to gzip event upload payloads.
max_retries (int) - Number of upload retries. Values below 0 are treated as 0.
sync_mode (bool) - If True, send each event synchronously instead of using background worker threads. This blocks the calling thread; in asyncio applications such as FastAPI, use AsyncPosthog instead.
timeout (int) - HTTP request timeout in seconds for event uploads.
thread (int) - Number of background consumer threads.
poll_interval (int) - Seconds between local feature flag definition refreshes.
personal_api_key (any) - Deprecated alias for secret_key. Still honored for backwards compatibility; prefer secret_key, which also accepts a Project Secret API Key.
disabled (bool) - If True, disable captures and API requests. Useful in tests.
disable_geoip (bool) - Whether to disable server-side GeoIP enrichment. Defaults to True.
is_server (bool) - Whether events are emitted from a server-side runtime. Defaults to True; set to False when using the SDK as a client/CLI so the device OS is attributed to the person normally.
historical_migration (bool) - Mark events as historical migration imports.
feature_flags_request_timeout_seconds (int) - Timeout in seconds for feature flag and remote config requests.
feature_flags_request_max_retries (int) - Number of retries for feature flag requests after network, transport, or timeout failures. Defaults to 1. Set to 0 to disable retries.
super_properties (any) - Properties merged into every captured event.
enable_exception_autocapture (bool) - Automatically capture uncaught exceptions.
log_captured_exceptions (bool) - Also log exceptions captured by error tracking.
project_root (any) - Root path used to determine in-app stack frames for captured exceptions. Defaults to the current working directory.
privacy_mode (bool) - For AI observability, capture usage metadata without prompt inputs or outputs.
before_send (any) - Optional callback that can modify or drop events before upload. Return None to drop an event.
flag_fallback_cache_url (any) - Optional feature flag fallback cache URL, such as memory://local/?ttl=300&size=10000 or a Redis URL.
enable_local_evaluation (bool) - Whether to poll feature flag definitions for local evaluation when a personal API key is configured.
flag_definition_cache_provider? (FlagDefinitionCacheProvider) - Optional external cache provider for sharing feature flag definitions across workers.
capture_exception_code_variables (bool) - Capture local variable values on exception stack frames.
code_variables_mask_patterns (any) - Variable-name patterns to mask when capturing code variables.
code_variables_ignore_patterns (any) - Variable-name patterns to omit when capturing code variables.
code_variables_mask_url_credentials (any) - Scrub credentials embedded in URLs/DSNs (e.g. user:pass@host) from captured code variables, regardless of the surrounding variable name. Defaults to True.
code_variables_detect_secrets (any) - Last-resort entropy-based detection that redacts high-entropy secret-looking values (API keys, tokens, strong passwords) sitting in innocuously-named variables, after the name and URL checks. Skips structured ids (UUIDs, ObjectIds, hashes). Defaults to True.
in_app_modules (UnionType[list[str], any]) - Module/package prefixes treated as in-app frames in captured exceptions.
enable_exception_autocapture_rate_limiting (bool) - Rate limit autocaptured exceptions client-side with a token bucket per exception type. Disabled by default.
exception_autocapture_bucket_size (int) - Maximum burst of autocaptured exceptions allowed per exception type (token bucket size, clamped to 0-100).
exception_autocapture_refill_rate (int) - Tokens restored per refill interval for each exception type’s bucket.
exception_autocapture_refill_interval_seconds (int) - Seconds between token refills for autocaptured exception rate limiting.
capture_mode (CaptureMode) - Capture wire protocol to use. Defaults to CaptureMode.V0 (legacy /batch/). Set CaptureMode.V1 (or pass the string "v1") to opt into /i/v1/analytics/events. When omitted, the POSTHOG_CAPTURE_MODE env var is consulted, then V0.
capture_compression (CaptureCompression) - Request-body compression for capture-v1 uploads (ignored in V0, which uses gzip). CaptureCompression.GZIP or DEFLATE (or the strings "gzip"/"deflate"). When omitted, the POSTHOG_CAPTURE_COMPRESSION env var is consulted, then the legacy gzip flag, then no compression.
secret_key (any) - A Personal API Key or Project Secret API Key, used to authenticate local feature flag evaluation, remote config payloads, and decrypted flag payloads. Example:: posthog.Client(project_api_key, secret_key=”phx_…”)
metrics? (dict)
enable_full_ai_capture (bool) - Route PostHog AI wrapper events through the dedicated AI capture endpoint and capture full AI content: skips string truncation and passes media (base64/data URIs) through unredacted. privacy_mode always wins. Defaults to False.
capture_trace_context (bool) - When OpenTelemetry is installed and a valid span is active at capture time, add its trace and span IDs as $trace_id and $span_id properties to events captured with capture() and capture_ai(), so they can be correlated with backend traces. Explicit $trace_id/$span_id values passed in properties win. Exception events (capture_exception) always attach these IDs regardless of this setting. Defaults to False.
_use_ai_lane (bool)
_enable_multimodal_capture (bool)
traces? (dict) - Config dict for distributed tracing: service_name, service_version, environment, resource_attributes, flush_interval (5 s), max_queue_size (2048), max_export_batch_size (512), max_live_spans (10000), max_span_age (3600 s), max_attributes_per_span (128), max_events_per_span (128), max_attribute_value_length (8192). before_span_send is a callable, or a list run in order, that receives each finished span as a dict (trace_id, span_id and parent_span_id are read-only) and returns it, edited, or None to drop it; a hook that raises drops the span. Tracing is off until this is provided. Spans export on a background timer even with sync_mode; serverless handlers should call flush() before returning. Defaults to None.

# Context usage
from posthog import identify_context, new_context
with new_context():
    identify_context('distinct_id_of_the_user')
    posthog.capture('user_signed_up')
    posthog.capture('user_logged_in')
    posthog.capture('some-custom-action', distinct_id='distinct_id_of_the_user')

# Set event properties
posthog.capture(
    "user_signed_up",
    distinct_id="distinct_id_of_the_user",
    properties={
        "login_type": "email",
        "is_free_trial": "true"
    }
)

flags = posthog.evaluate_flags(
    "user_123",
    person_properties={"plan": "enterprise"},
)
if flags.is_enabled("new-dashboard"):
    render_new_dashboard()
posthog.capture("page_viewed", distinct_id="user_123", flags=flags)

is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')
if is_my_flag_enabled:
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

enabled_variant = posthog.get_feature_flag('flag-key', 'distinct_id_of_your_user')
if enabled_variant == 'variant-key': # replace 'variant-key' with the key of your variant
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

is_my_flag_enabled = posthog.feature_enabled('flag-key', 'distinct_id_of_your_user')

if is_my_flag_enabled:
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = posthog.get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

flag_result = posthog.get_feature_flag_result('flag-key', 'distinct_id_of_your_user')
if flag_result and flag_result.get_value() == 'variant-key':
    # Do something differently for this user
    # Optional: fetch the payload
    matched_flag_payload = flag_result.payload

posthog = Posthog("<ph_project_api_key>", traces={"service_name": "checkout-api"})

with posthog.start_span("POST /checkout", parent=request.headers.get("traceparent")) as span:
    span.set_attribute("plan", user.plan)
    with posthog.start_span("db.query", kind="client"):
        ...
    outgoing_headers = {"traceparent": span.traceparent()}

# Context and capture usage
from posthog import new_context, identify_context, tag_context, capture
# Enter a new context (e.g. a request/response cycle, an instance of a background job, etc)
with new_context():
    # Associate this context with some user, by distinct_id
    identify_context('some user')

    # Capture an event, associated with the context-level distinct ID ('some user')
    capture('movie started')

    # Capture an event associated with some other user (overriding the context-level distinct ID)
    capture('movie joined', distinct_id='some-other-user')

    # Capture an event with some properties
    capture('movie played', properties={'movie_id': '123', 'category': 'romcom'})

    # Capture an event with some properties
    capture('purchase', properties={'product_id': '123', 'category': 'romcom'})
    # Capture an event with some associated group
    capture('purchase', groups={'company': 'id:5'})

    # Adding a tag to the current context will cause it to appear on all subsequent events
    tag_context('some-tag', 'some-value')

    capture('another-event') # Will be captured with `'some-tag': 'some-value'` in the properties dict

# Set event properties
from posthog import capture
capture(
    "user_signed_up",
    distinct_id="distinct_id_of_the_user",
    properties={
        "login_type": "email",
        "is_free_trial": "true"
    }
)

from posthog import evaluate_flags, capture
flags = evaluate_flags("user_123", person_properties={"plan": "enterprise"})
if flags.is_enabled("new-dashboard"):
    render_new_dashboard()
capture("page_viewed", distinct_id="user_123", flags=flags)

# Boolean feature flag
from posthog import feature_enabled, get_feature_flag_payload
is_my_flag_enabled = feature_enabled('flag-key', 'distinct_id_of_your_user')
if is_my_flag_enabled:
    matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

# Multivariate feature flag
from posthog import get_feature_flag, get_feature_flag_payload
enabled_variant = get_feature_flag('flag-key', 'distinct_id_of_your_user')
if enabled_variant == 'variant-key':
    matched_flag_payload = get_feature_flag_payload('flag-key', 'distinct_id_of_your_user')

import posthog
posthog.traces = {"service_name": "checkout-api"}

with posthog.start_span("POST /checkout", parent=request.headers.get("traceparent")) as span:
    span.set_attribute("plan", user.plan)
    with posthog.start_span("db.query", kind="client"):
        ...
    outgoing_headers = {"traceparent": span.traceparent()}